Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

JACS: JSON Agent Communication Standard

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

Start With The Boundary

Most deployments start in one of four places:

• Core signing: sign JSON, files, Markdown/text, images, or Rust email payloads directly.
• MCP: run jacs-compat mcp as a local tool server, or add signing around an existing MCP transport.
• Frameworks: add provenance at LangChain, LangGraph, FastAPI, Express, Koa, or Vercel AI SDK boundaries.
• A2A and agreements: exchange signed artifacts or require multiple agents to sign off.

What JACS Gives You

• Persistent agent identity with encrypted private keys
• Tamper-evident signed JSON and file envelopes
• Inline Markdown/text signatures that stay readable in place
• Embedded PNG/JPEG/WebP signatures for media provenance
• Rust email signing and verification with field-level content hashes
• Trust policies and local trust-store workflows
• Cross-language verification across Rust, Python, Node.js, and Go

For platform workflows around verified documents, agent behavior, benchmarks, and hosted JACS identity flows, see HumanAssisted/haiai.

Best Entry Points

1. Which Integration?
2. Quick Start
3. Use Cases
4. MCP Overview
5. Inline Text Signatures
6. Image and Media Signatures
7. Email Signing and Verification

Install

Rust CLI and MCP server

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

Python

pip install jacs

Node.js

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

npm install @hai.ai/jacs

Go

go get needs the matching CGo shared library. Each release publishes both the semantic module tag and native libraries for macOS and Linux. Follow Go Installation and Quick Start for the verified installer or a full-repository source build.

What This Book Does Not Claim

• MCP and A2A are different boundaries: MCP is model-to-tool; A2A is agent-to-agent discovery and exchange.
• JACS does not require a registry, blockchain, or central server.
• Email signing is currently documented as a Rust core API, not a CLI or Python/Node/Go binding surface.

Community

• GitHub Repository
• Issue Tracker

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

What is JACS?

JACS is a cryptographic provenance layer for AI agents and the artifacts they produce. It gives an agent a persistent signing identity, wraps important outputs in tamper-evident signatures, and lets other systems verify origin and integrity later.

Use JACS when data crosses a trust boundary: another service, another agent, another organization, a user-facing audit trail, or a file that must remain verifiable after it leaves the process that created it.

The Problem

Agent systems increasingly produce artifacts that other systems act on:

• JSON tool results, reports, memories, and configs
• Markdown plans, design docs, and release notes
• Images, screenshots, charts, and generated media
• Email messages and attachments
• A2A artifacts, MCP tool calls, and multi-agent approvals

Logs can say what happened, but they are usually controlled by the same system that produced the data. JACS attaches proof to the artifact itself.

Core Ideas

What Verification Proves

Verification answers two practical questions:

1. Did the signer with this public key sign these canonical bytes?
2. Has the signed content changed since it was signed?

Verification does not prove first creation, copyright ownership, human authorship, or that a real-world statement is true. It gives you cryptographic accountability for the artifact.

Where JACS Fits

flowchart LR
    A["Agent or service"] --> B["Create artifact"]
    B --> C["Sign with JACS"]
    C --> D["Share or store"]
    D --> E["Verify before trust"]

JACS does not replace your application protocol. It works with CLI jobs, Rust services, Python and Node frameworks, MCP tools, A2A exchange, and file-based workflows.

When To Use It

• A downstream system should verify who produced an artifact.
• Multiple agents or teams need an auditable handoff.
• A document, image, or email must stay verifiable outside your database.
• You need open source signing primitives without a mandatory central registry.

When Not To Use It

• Everything stays inside one trusted process and logs are enough.
• You only need accidental-corruption detection.
• There is no signer identity or audit requirement.

Next Steps

• Quick Start
• Which Integration?
• Use Cases

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Which JACS Path Should I Use?

Choose the smallest supported integration that matches the boundary you need to secure.

Start Here

When You Probably Do Not Need JACS

• Everything stays inside one service you control and 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: file, API response, framework tool, MCP call, image, email, or A2A artifact.
3. Add trust policy when other agents, services, or organizations enter the workflow.
4. Add agreements, DNS, or attestations only when the deployment needs them.

Start with the boundary you need to secure now.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Use Cases

These are current JACS use cases, not speculative integrations.

1. Keep JSON and files verifiable

Use JACS when a report, memory, config, policy, or audit artifact needs to stay verifiable after it leaves the process that created it.

Start with:

• Quick Start
• Verifying Signed Documents
• Working with Documents

What JACS adds:

• Self-contained signed envelopes
• Re-verification at read time
• Cross-language compatibility across Rust, Python, Node.js, and Go

2. Sign Markdown in place for review

Use JACS when a README, design doc, policy, or release note needs visible content and verifiable sign-off in the same file.

Start with:

• Inline Text Signatures

JACS_CONFIG=./reviewer-a.config.json jacs-compat sign-text DESIGN.md
JACS_CONFIG=./reviewer-b.config.json jacs-compat sign-text DESIGN.md
jacs-compat verify-text DESIGN.md

What JACS adds:

• A readable signature block appended at the end
• Multi-signer review without sidecar JSON
• Permissive or strict verification modes

3. Embed provenance in images

Use JACS when a photo, chart, screenshot, or AI-generated image needs verifiable signer identity without a separate metadata file.

Start with:

• Image and Media Signatures

jacs-compat sign-image photo.png --out signed.png
jacs-compat verify-image signed.png
jacs-compat extract-media-signature signed.png

What JACS adds:

• Embedded PNG iTXt, JPEG APP11, or WebP XMP signatures
• Pixel-content integrity checks
• Optional robust mode for PNG/JPEG metadata-strip threat models

4. Sign email with Rust

Use JACS when raw RFC 5322 email needs a verifiable signature attachment and field-level content verification.

Start with:

• Email Signing and Verification

What JACS adds:

• jacs-signature.json MIME attachment
• Header, body, and attachment hashes
• Forwarding chains through parent signature hashes

Email signing is currently documented as a Rust core API via jacs::email, not as a CLI or Python/Node/Go binding surface.

5. Secure a local MCP tool server

Use JACS when an MCP client needs local document signing or supplied-key integrity checks.

Start with:

• MCP Overview

For keyless verification, install the CLI and start the explicit verification profile:

cargo install jacs-cli-compat --locked
jacs-compat mcp --profile verify-only

For document signing, configure a password source before creating an identity, or use an existing signing config. Then start the explicit signing profile:

jacs-compat quickstart --name mcp-agent --domain mcp-agent.example
jacs-compat mcp --profile local-sign --config ./jacs.config.json

To also enable scoped text/image tools, prefix the final command with JACS_MCP_BASE_DIR=/path/to/content. Each server command runs until the MCP client closes it; verification and signing are alternative startup choices.

What JACS adds:

• A ready-made stdio MCP server
• Explicit-key document verification by default; JSON/Agreement tools with local-sign
• Five text/image tools only with local-sign, a signing config and JACS_MCP_BASE_DIR
• Local private-key custody; no HTTP listener

Signatures establish key-backed provenance, not per-action human approval, truth or authority. Loading a config alone does not grant signing. Trust/admin capabilities remain unavailable through these profiles; inspect tools/list for the running process's actual inventory.

6. Add provenance to framework boundaries

Use JACS when an existing app already has a boundary such as LangChain tool output, FastAPI response, Express middleware, or Koa middleware.

Start with:

• Python Framework Adapters
• Node.js LangChain.js
• Express Middleware
• Koa Middleware

What JACS adds:

• Signed tool results and responses
• Optional strict verification at adapter boundaries
• Minimal changes to existing framework code

7. Exchange artifacts across agents or organizations

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

Start with:

• A2A Interoperability
• A2A Quickstart
• Multi-Agent Agreements

What JACS adds:

• Signed A2A artifacts
• Trust policies for admission control
• Agreement-v2 inspection of mathematical signature coverage; M-of-N, role, status and algorithm policy claims require separate application evaluation

Agreement-v2 math is not policy acceptance: its native valid and policyAccepted stay false. Quorum counts, human/notary labels and final status cannot establish human approval or authority. See the Agreement-v2 guide for the inspection/report distinction.

8. Publish identity without a central auth service

Use JACS when external systems need to verify an agent identity without putting a shared server in the middle.

Start with:

• DNS-Based Verification
• DNS Trust Anchoring

What JACS adds:

• Public key fingerprint anchoring
• Local trust-store workflows
• Local private-key custody

9. Add hosted verification with HAI.AI

Use HumanAssisted/haiai when you want platform workflows for verified documents, agent behavior, benchmarks, and hosted JACS identity flows.

JACS remains the local open source signing and verification layer. HAI.AI is the hosted platform path around those identities and artifacts.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Core Concepts

JACS is a portable signing and verification system for JSON documents. Its main primitive is a verifiable JSON envelope: canonical bytes, schema-declared structure, content hash, signer identity, signing algorithm, and cryptographic signature.

Agents

An Agent is an identity that can create, sign, and verify documents.

{
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsVersion": "123e4567-e89b-12d3-a456-426614174000",
  "jacsType": "agent",
  "jacsAgentType": "ai",
  "jacsAgentDomain": "agent.example.com"
}

Agents have stable IDs, versioned identity documents, and cryptographic keys. A2A capabilities are represented through A2A Agent Cards.

Documents

A Document is any JSON object signed with the JACS header/signature wrapper.

{
  "$schema": "https://hai.ai/schemas/header/v1/header.schema.json",
  "jacsId": "doc-uuid-here",
  "jacsVersion": "version-uuid-here",
  "jacsType": "document",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsLevel": "artifact",
  "content": {
    "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": ["$schema", "jacsId", "jacsVersion", "jacsType", "content"]
  }
}

Application-specific meaning belongs inside the payload or in a custom schema that extends the header.

Agreements

Agreements collect multiple signatures over the same document payload.

{
  "jacsAgreement": {
    "agentIDs": ["agent-1-uuid", "agent-2-uuid"],
    "question": "Do you approve this change?",
    "context": "Deployment approval",
    "quorum": 2,
    "signatures": []
  },
  "jacsAgreementHash": "hash-of-agreement-content"
}

This legacy sidecar permits signature inspection only: its participant list, roles, question, context and quorum are unauthenticated. A claimed completion status is not consent-policy acceptance. New portable consent uses Agreement v3; native Agreement v2 inspection likewise keeps policyAccepted=false. See the agreement guide for the version boundaries.

Verification

When consuming signed documents, verify in one of two ways:

• With a loaded agent: call verify(signedDocument) using the configured trust store and key resolution.
• Without loading an agent: call verify_standalone(signedDocument, options) with explicit key-resolution options.

Cryptographic Security

JACS signs canonical JSON bytes. Verification checks the content hash, signature fields, signer identity, algorithm, and public key.

Supported algorithms:

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Quick Start Guide

Get a persistent agent identity, sign data, and verify it.

Start with MCP

Install the portable CLI and start its default verification-only MCP server:

cargo install jacs-cli --locked
jacs mcp

{
  "mcpServers": {
    "jacs": { "command": "jacs", "args": ["mcp"] }
  }
}

Verification requires independently trusted public evidence. A valid signature proves integrity under that key; your application decides identity and authority.

Portable CLI

Create an encrypted identity, sign JSON and verify with the exported public identity:

mkdir -m 700 .jacs
jacs create --output .jacs/agent.json > public-identity.json
printf '%s' '{"message":"hello"}' | jacs sign --agent .jacs/agent.json --input - > signed.json
jacs verify --public-identity public-identity.json --input signed.json

The terminal prompts for the password. For an MCP client that can provide the host's configured secret source, explicitly enable signing with jacs mcp --profile local-sign --agent /absolute/path/to/.jacs/agent.json. Use the same arguments in its mcpServers configuration. See the current MCP guide for secret handling and the available tools.

The remaining native examples use a separate installation:

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

This creates jacs.config.json and persistent native keys for direct libraries and extended text/image commands. The native MCP profiles use jacs-compat mcp; see extended profiles.

Python

python -m pip install jacs==0.16.1

import jacs.simple as jacs

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

Node.js

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

npm install --save-exact @hai.ai/jacs@0.16.1

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

await jacs.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
});

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

Sign Markdown or text

jacs-compat sign-text README.md
jacs-compat verify-text README.md
jacs-compat verify-text --strict README.md

sign-text appends a -----BEGIN JACS SIGNATURE----- block at the end of the file. The original content remains readable and can be counter-signed by another agent.

See Inline Text Signatures for multi-signer flows, strict mode, and --key-dir.

Sign images

jacs-compat sign-image photo.png --out signed.png
jacs-compat verify-image signed.png
jacs-compat extract-media-signature signed.png

JACS embeds the signature in PNG, JPEG, or WebP metadata. See Image and Media Signatures for overwrite policy, robust mode, and verification details.

Native password bootstrap

Choose one explicit password source for jacs-compat: the host-provided JACS_PRIVATE_KEY_PASSWORD, or JACS_PASSWORD_FILE pointing to a protected secret file. Setting both is an error. When neither is set, the native CLI can use the OS keychain; see password and keychain setup.

Python and Node quickstart can generate a password in-process. Retain it through your host secret source for later processes; see the language quickstart guide.

Algorithm

The default signing algorithm is pq2025 (ML-DSA-87 / FIPS-204). Use the user-facing ed25519 choice if you need a smaller classical signature. JACS stores and emits the canonical Ed25519 wire label as ring-Ed25519:

jacs-compat quickstart --name my-agent --domain my-agent.example.com --algorithm ed25519

Next steps

• Which Integration?
• Verifying Signed Documents
• MCP Overview

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Multi-Agent Agreements

Agreement v2 records terms and agent consent signatures in a standalone jacsType: "agreement" document. Its verifier inspects mathematical and structural checks. It does not accept the full authorization policy or prove human approval, even when the supplied quorum produces a final status.

Use this walkthrough to inspect agent provenance. An application must separately establish the authority and any exact-action human approval required before acting.

The Lifecycle

Create agreement -> append transcript refs -> collect signer/notary signatures -> inspect math and policy scope

Python

All three demo identities are controlled by this code, including the agent labeled notary; no person or external notary approves anything here.

The three agents are persistent and share one data_directory so each can resolve the others' public keys when verifying. Independent ephemeral() agents keep keys in memory only and cannot verify each other's signatures.

import os
import secrets
import tempfile
from pathlib import Path

from jacs import SimpleAgent

os.environ["JACS_KEYCHAIN_BACKEND"] = "disabled"  # throwaway demo only
PASSWORD = secrets.token_urlsafe(32)
workspace = Path(tempfile.mkdtemp(prefix="jacs_multi_agent_"))
shared_data = workspace / "shared_data"  # all agents share this so keys resolve


def make_agent(name, agent_type="ai"):
    agent, info = SimpleAgent.create_agent(
        name=name,
        password=PASSWORD,
        algorithm="ring-Ed25519",
        data_directory=str(shared_data),
        key_directory=str(workspace / f"{name}_keys"),
        config_path=str(workspace / f"{name}.config.json"),
        agent_type=agent_type,
    )
    return agent, info


agent_a, a = make_agent("agent-a")
agent_b, b = make_agent("agent-b")
notary, n = make_agent("demo-notary")

agreement = agent_a.create_agreement_v2({
    "title": "Bounded refund authorization",
    "description": "Demo refund terms for agent signature inspection; no refund is authorized.",
    "terms": "Agent B may issue a refund up to $25 for order 123 after Agent A approval.",
    "termsFormat": "text/markdown",
    "status": "proposed",
    "parties": [
        {"agentId": a["agent_id"], "agentType": "ai", "role": "signer"},
        {"agentId": b["agent_id"], "agentType": "ai", "role": "signer"},
        {"agentId": n["agent_id"], "agentType": "ai", "role": "notary"},
    ],
    "signaturePolicy": {
        "partyQuorum": "all",
        "witnessRequired": 0,
        "notaryRequired": 1,
        "minimumStrength": "classical",
    },
    "controllers": [a["agent_id"], b["agent_id"], n["agent_id"]],
})

agreement = agent_a.sign_agreement_v2(agreement, "signer")
agreement = agent_b.sign_agreement_v2(agreement, "signer")
agreement = notary.sign_agreement_v2(agreement, "notary")

# The demo notary resolves the signers' public keys from shared storage.
report = notary.verify_agreement_v2(agreement)
assert report["mathematicalChecksValid"] is True
assert report["valid"] is False
assert report["policyAccepted"] is False
assert report["overallScope"] == "consent_signatures_only"
assert report["expectedStatus"] == "final"  # structural diagnostic only

This abbreviated snippet leaves its temporary workspace for inspection; remove it when finished. The runnable version includes transcript references and adversarial checks, and cleans up its temporary keys:

python examples/agreement_v2_three_party.py

What the Report Means

• mathematicalChecksValid covers the native hash, signature and structural checks. Inspect errors for failures and notes, verifiedChainDepth and chainFullyVerified for lineage coverage limits.
• Consent signatures bind the agreement identity and consent hash; signatures made with a nonempty transcript also bind its prefix at signing. Later unsigned transcript entries are not retroactively covered.
• Signer counts, quorum, witness/notary requirements and expectedStatus are diagnostics against the supplied document. Neither a count nor status: "final" is an accepted policy verdict.
• Helpers check membership, role and controller lists. These checks do not establish portable role/controller authority or a person's approval. Changing an agent's label to human does not add human approval evidence.
• valid and policyAccepted remain false, including for the successful mathematical inspection above. Do not turn either field into true or treat mathematicalChecksValid as permission to act.

Legacy Sidecar Agreements

The older create_agreement() / sign_agreement() / check_agreement() API still exists for adding jacsAgreement metadata to an arbitrary signed document. It supports signature inspection of an existing payload; those signatures alone do not establish human approval or the complete application policy.

V2 adds standalone terms, transcript-prefix evidence and branch helpers. Moving to v2 does not create an actionable authorization.

Next Steps

• Agreement v2 Developer Guide
• Creating and Using Agreements
• Security Model

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Verifying Signed Documents

Verify a JACS-signed document in under 2 minutes. Verification checks that the document has not changed and was signed by the key selected under your trust policy. A signature alone does not establish a real-world identity or permission to act.

Verification does NOT require creating an agent. You need the signed document and independently trusted public evidence for its signer.

Raw JSON is decoded strictly before signing, canonicalization, or verification. Duplicate object names are rejected at every nesting level, including names that become equal after JSON escape decoding (for example, agentID and agent\u0049D). This prevents two consumers from interpreting the same signed bytes with different first-key/last-key rules. Repeated values in arrays are ordinary JSON and remain supported.

Strict vs permissive verification

verify-text and verify-image use a permissive default: a missing signature is a typed status, not an error. Strict mode opts in to error-on-missing. The choice maps onto every binding the same way.

Pre-existing verify surfaces (jacs-compat verify, jacs-compat document verify, jacs.verify) are unaffected — they keep their existing exit codes and return shapes.

For hands-on examples see Inline Text Signatures and Image and Media Signatures.

Portable CLI

cargo install jacs-cli --locked
jacs verify --public-identity trusted-public-identity.json --input signed-document.json

Obtain trusted-public-identity.json independently of the untrusted document. The portable CLI uses explicit --input and --public-identity arguments; it does not use the native config or remote/key-directory options below.

Install cargo install jacs-cli-compat --locked for the extended native commands.

CLI: jacs-compat verify

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

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

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

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

# Specify a directory containing public keys
jacs-compat 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-compat 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');

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-compat 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-compat agent lookup example.com

This inspection command fetches and prints https://example.com/.well-known/jacs-pubkey.json and the DNS TXT record at _v1.agent.jacs.example.com. It does not compare the fetched key against the TXT fingerprint or establish trust. Use the verification APIs and an independently selected key for that decision.

CLI verification with DNS

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

# Require strict DNSSEC validation
jacs-compat 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.

Legacy-v1 signatures that lack signatureContentVersion are denied by default because their signer, timestamp, nonce, and algorithm metadata was never covered by the signature. Use the migration API to re-sign them as v2. For a narrowly audited archive workflow, JACS_ALLOW_LEGACY_SIGNATURE_CONTENT=true enables payload-only compatibility; verification results deliberately leave signer, agent-version, and timestamp fields empty. Do not use that mode for authorization or identity attribution. The historical JACS_REJECT_LEGACY_SIGNATURE_CONTENT=true setting remains supported and takes precedence.

This is tested on every commit: current v2 fixtures verify by default across bindings, while committed v1 fixtures prove both default rejection and explicit payload-only compatibility. 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

Native document verification uses JACS_KEY_RESOLUTION (environment only), defaulting to local,registry. Local storage supplies cached/trusted public keys; registry lookup requires the relevant network policy. Adding dns, with DNS and remote key fetch allowed and a configured or signed publisher domain, fetches the exact signed version's key over HTTPS and pins it to the TXT record's raw-key fingerprint. Discovered keys do not enroll a trusted identity. See the key discovery guide, DNS verification and trust enrollment.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

What Is an Attestation?

Attestations bind a signer to claims and evidence references.

A JACS attestation is a cryptographically signed document that goes beyond checking a signature. It records claims, evidence and the signer's stated reasoning. The relying application decides whether those claims are true and whether the signer and evidence are trusted.

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 evidence and derivation checks. Freshness is checked when maxEvidenceAge is configured; claim truth, identity and application authorization are not established by this report.

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.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

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. A valid JACS signature links the covered content to the signing key and detects changes to that content. Binding the key to an agent or person requires trusted identity evidence; the signature alone does not establish who created the content, whether its claims are true, or whether a person approved it. 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:

These policies parse legacy cards, not A2A 1.0. 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).

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Deployment Compatibility

The release inventory records verified 0.16.1 packages, platforms, checksums and provenance. Prebuilt, CI-tested and runtime-tested coverage differ; source compilation alone does not establish them. Later source changes need separate release evidence.

Declared toolchain baselines

Platform decisions

Windows

The observed Windows prebuilt is the x86_64 CLI only. Do not infer Windows Python or Node support from the CLI artifact: PyPI 0.16.1 has no Windows wheel, npm 0.16.1 has no Windows .node binary, and the Go bindings have no Windows CGo linker directive or native asset. The browser/WASM source may be portable at the WebAssembly level, but no Windows browser runtime lane was recorded.

Linux libc and architecture

“Linux” is not one ABI:

• Python glibc wheels are tagged manylinux_2_28; systems with glibc older than 2.28 cannot use those wheels. The observed musllinux wheel is x86_64 only.
• Node 0.16.1 ships glibc x86_64 and arm64 binaries and a musl x86_64 binary; there is no musl arm64 binary.
• CLI 0.16.1 ships glibc Linux x86_64 and arm64 archives. No musl CLI archive is recorded in the shipped inventory.
• A source build is a separate claim. It may work on additional targets when the required compiler, linker, libc headers, Rust dependencies, and system libraries are available, but that is not prebuilt support.

Containers, Lambda, and serverless platforms

A container orchestrator does not remove the native ABI requirement. Match the image architecture and libc to an actual wheel, .node file, CLI archive, or Go shared library. For example, the observed Python musllinux wheel supports an x86_64 Alpine-style image, while its glibc wheels require glibc 2.28 or newer.

This x86_64 example deliberately requires a prebuilt musllinux wheel instead of silently falling back to an undocumented source build:

FROM --platform=linux/amd64 python:3.12-alpine
RUN python -m pip install --only-binary=:all: "jacs==0.16.1"
ENV JACS_KEYCHAIN_BACKEND=disabled
WORKDIR /app
COPY . /app
CMD ["python", "main.py"]

AWS Lambda, Vercel, Cloudflare Workers, Deno, and Bun do not have dedicated runtime-smoke lanes in the recorded matrix. Treat them as unverified. For Lambda or another native serverless runtime, build and test a layer against the exact runtime image and architecture; do not assume a generic Linux artifact is ABI-compatible. Browser-only runtimes require the published @hai.ai/jacs-wasm package.

For headless native environments, set JACS_KEYCHAIN_BACKEND=disabled and supply key passwords through the deployment platform's secret mechanism. Do not bake passwords or private keys into an image.

Browser/WASM capability limits

The WASM surface defaults to pq2025 identities, with explicit Ed25519 and ES256 compatibility, and can sign and verify JSON, and use encrypted browser persistence. It does not expose native filesystem storage, DNS resolution, MCP, or the native CLI. Browser WebAssembly memory is JavaScript-visible; source compatibility is not a claim of hardware-backed key isolation. See the WASM package security caveats before using it for long-lived signing keys.

Building from source

Source builds require the full repository because the language bindings use path dependencies on the Rust crates:

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

# Python development build
python -m pip install maturin
make build-jacspy

# Node development build
make build-jacsnpm

# Go native library + module
make build-jacsgo

# Browser package
make build-wasm

Rust 1.97 or newer is required. Native language bindings also require their language toolchain, a C linker, and platform system dependencies. A successful source build on one machine does not add that target to the published-artifact matrix.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Troubleshooting

Common issues and solutions when installing or using JACS.

Installation Issues

pip install fails

Published 0.16.1 wheels and this source checkout require Python 3.11–3.14. If no pre-built wheel exists for your platform, install the Rust toolchain and build from source:

pip install maturin
make build-jacspy  # from the repository root

npm install fails

Native npm binaries cover macOS x64/arm64, Linux x64/arm64 for glibc and Linux x64 for musl. There is no Windows addon; a Windows CLI archive is a separate artifact. For custom source builds, use make build-jacsnpm from the repository root with the documented Node and Rust toolchains.

Alpine Linux / musl libc

Published 0.16.1 includes a Python musllinux x86_64 wheel and an npm musl x86_64 addon; neither has a musl arm64 build. CLI archives are glibc-only; the Python/npm CLI shims reject musl even when library APIs work. Match the artifact to architecture and libc; see deployment compatibility.

Configuration Issues

Config not found

Run jacs-compat 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 jacs-compat, you may also set JACS_PASSWORD_FILE to a file that contains only the password, or use jacs-compat keychain set to store the password in the OS keychain. Set exactly one explicit source; if both env var and password file are set, CLI fails by design. The OS keychain is only consulted when neither env var nor password file is present.

Algorithm detection failed

Set jacs_agent_key_algorithm in the config, or pass the algorithm explicitly to quickstart(...) / create(...). User-facing values are pq2025 and ed25519; the legacy input alias and canonical Ed25519 wire label are ring-Ed25519.

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

# Python binding
make build-jacspy  # from the repository root

# Node.js binding
make build-jacsnpm

Requires Rust 1.97+ (install via rustup).

Getting Help

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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Rust and CLI installation

Portable CLI and MCP

cargo install jacs-cli --locked
jacs mcp

The jacs binary starts MCP in verification-only mode by default. For signing, create an encrypted identity and explicitly select it; see the quick start and current MCP guide.

Native integrations

The extended commands documented in this reference use a separate executable:

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

Its jacs.config.json, key directories, DNS, storage and extended MCP profiles belong to the native compatibility workspace. See CLI usage.

Rust libraries

For portable cryptography without I/O:

[dependencies]
jacs-core = "=0.16.1"
serde_json = "1"

For native identity, storage and integrations:

[dependencies]
jacs = "=0.16.1"
serde_json = "1"

Native optional features include a2a, agreements, attestation, s3, sqlx-sqlite, otlp-logs, otlp-metrics and otlp-tracing; SQLite is enabled by default. Select only the features your integration needs. The library guide covers the native API.

Publication and platforms

The release inventory records 0.16.1 across 16 of the 17 Rust crates (jacs-surrealdb stays at 0.15.0), CLI archives and language packages. Cargo builds libraries from source. CLI archives cover macOS arm64/x86_64, Linux glibc arm64/x86_64 and Windows x86_64; this does not imply Windows Python, Node or Go native artifacts. See deployment compatibility.

The browser package is published as @hai.ai/jacs-wasm; see its installation guide. Release 0.16.0 is the first in which the identity-standard exports reuse the persistent ML-DSA-87 identity.

Build this checkout

Source builds require Rust 1.97 or newer (Edition 2024), a linker and any native system dependencies. From the repository root:

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

The active workspace contains jacs-core, jacs-wasm, jacs-mobile, jacs-mcp and jacs-cli. Native packages use archive/native/Cargo.toml; for example:

cargo check --manifest-path archive/native/Cargo.toml -p jacs --locked

Use the developer commands for binding builds and the shared Rust cache setup before substantial builds. Never place a key password in command arguments. Use the prompt or host secret source documented for the selected CLI.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

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, and agreements.

Getting Help

# General help
jacs --help

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

Commands Overview

Initialization

Quick Start

# Initialize everything in one step
jacs-compat 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-compat binary. No separate install step needed.

# Start the MCP server (stdio transport)
JACS_CONFIG="$PWD/jacs.config.json" jacs-compat mcp

Configuration Commands

Create Configuration

jacs-compat config create

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

Read Configuration

jacs-compat config read

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

Agent Commands

Create Agent

jacs-compat agent create --create-keys true

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

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

Options:

Verify Agent

# Verify agent from config
jacs-compat agent verify

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

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

Options:

DNS Commands

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

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

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

Options:

Lookup Agent

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

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

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

Document Commands

Create Document

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

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

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

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

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

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

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

Options:

Update Document

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

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

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

Options:

Verify Document

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

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

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

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

Options:

Extract Embedded Content

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

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

Agreement Commands

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

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

# Sign an agreement
jacs-compat 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=./custom-config.json jacs-compat agent verify

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

Common Workflows

Create and Sign a Document

# 1. Initialize (if not done)
jacs-compat init

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

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

Multi-Agent Agreement

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

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

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

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

Verify Another Agent

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

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

Exit Codes

Success is 0; operation/verification errors generally use 1. Argument parsing uses 2, as does permissive text/image inspection with no signature. Check the error reference and the command's result fields; a completed inspection is not an authorization decision.

Next Steps

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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Creating an Agent

An agent is the fundamental identity in JACS: an entity with signing keys that can create, sign, and verify documents.

What is an Agent?

A JACS agent is:

• A stable UUID identity
• A holder of cryptographic signing keys
• A self-signed identity document
• An optional DNS-verifiable identity

Capabilities for A2A interoperability live in A2A Agent Cards. The JACS agent document stays focused on identity and signing metadata.

Creating Your First Agent

jacs-compat init

This creates:

• Configuration file
• Cryptographic key pair
• Initial agent document

Manual Creation

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

Custom Agent Definition

Create an agent definition file:

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

Then create the agent:

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

Agent Types

Cryptographic Keys

New agents hold two key roles:

Use ed25519 as the user-facing creation label; configuration and signed documents use the canonical ring-Ed25519 wire label.

The compatibility key is minted eagerly at creation (skip with CreateAgentParams::builder().no_compat_key(true) or the CLI --no-compat-key). Existing agents migrate explicitly:

let compat = agent.add_compat_key()?; // role, algorithm, RFC 7638 kid, paths
let info = agent.ecosystem_key_info()?; // typed KeyNotFound when absent

Roles are recorded in jacs_keys/jacs.keyring.json (metadata only); the ES256 private key uses the same AES-256-GCM + Argon2id envelope and 0600 permissions as the native root.

Verifying Agents

jacs-compat agent verify
jacs-compat agent verify -a ./path/to/agent.json
jacs-compat agent verify --require-dns
jacs-compat agent verify --require-strict-dns

HTTP protocol helpers

SimpleAgent signs request context and complete response envelopes without exposing its internal mutex:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
use jacs::{protocol::verify_signed_event_with_trusted_keys, simple::SimpleAgent};

let (agent, _) = SimpleAgent::ephemeral(Some("ed25519"))?;
let body = br#"{"action":"approve"}"#;
let authorization = agent.build_request_auth_header(
    "POST",
    "https://api.example.com/v1/jobs?mode=strict",
    body,
    "jobs-api",
)?;

let envelope = agent.sign_response(&serde_json::json!({"decision": "allow"}))?;
let signer_id = envelope["jacsSignature"]["agentID"]
    .as_str()
    .ok_or("missing signer ID")?;
let keys = HashMap::from([(signer_id.to_owned(), agent.get_public_key()?)]);
let verified = verify_signed_event_with_trusted_keys(&envelope, &keys)?;
assert!(authorization.starts_with("JACS v2."));
assert_eq!(verified.data["decision"], "allow");
}

The request header binds method, absolute URL including query, exact body bytes, audience, key, time, and nonce. The response signature covers both data and every envelope field. The verifier rejects unsigned/plain events, unknown signers, legacy payload-only envelopes, and any metadata or payload mutation. See Security for server replay-store requirements and migration from unbound headers.

The supplied key map is the trust boundary. A valid signature proves possession of that key, not a real-world identity unless the application established the signer-to-key association under its configured policy.

Agent Document Structure

{
  "$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",
  "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", "jacsAgentDomain", "name"]
  }
}

Best Practices

1. Protect private keys.
2. Prefer strong signing algorithms.
3. Enable DNS verification for production agents.
4. Keep A2A capabilities in the A2A Agent Card.
5. Track agent document versions.

Next Steps

• Working with Documents
• Agreements
• DNS Verification

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

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-compat document create -f my-document.json

This adds JACS headers and a signature, saves the document, and prints the exact path. Pass --json for a machine-readable document key/path result.

From a Directory

Process multiple documents at once:

jacs-compat document create -d ./documents/

With Custom Schema

Validate against a custom JSON schema:

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

Output Options

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

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

# Verbose output
jacs-compat 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-compat document create -f my-document.json --attach ./report.pdf

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

Embed vs. Reference

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

# Reference files (smaller document, files stored separately)
jacs-compat 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-compat 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-compat document verify -f ./document.json -s ./schema.json

Verify Directory

jacs-compat document verify -d ./documents/

Verbose Output

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

Updating Documents

Updates create a new version while maintaining the same jacsId:

jacs-compat 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-compat document update -f ./original.json -n ./modified.json --attach ./new-file.pdf

Extracting Embedded Content

Extract attachments from a document:

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

Extract from multiple documents:

jacs-compat document extract -d ./documents/

Document Payloads

Generic Documents

JACS signs arbitrary JSON payloads through the header schema:

{
  "$schema": "https://hai.ai/schemas/header/v1/header.schema.json",
  "jacsType": "document",
  "content": {
    "subject": "Status update",
    "body": "The requested work is complete."
  }
}

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-compat document create -f ./document.json -a ./other-agent.json

Verify Document from Unknown Agent

# Verify with strict DNS requirement
jacs-compat 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-compat document create -f ./proposal.json -o ./signed-proposal.json

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

Track Document Changes

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

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

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

Process Multiple Documents

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

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

Next Steps

• Agreements - Multi-agent consent
• Custom Schemas - Create your own schemas

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Creating and Using Agreements

Agreement v2 is the native compatibility agreement model. It is a standalone jacsType: "agreement" document that captures terms, parties, transcript references, signature policy, consent signatures, and version lineage.

Use Agreement v2 to inspect existing native agreement signatures and claimed status. The report always keeps valid=false and policyAccepted=false: party proofs do not authenticate the complete role, quorum, lineage or finalization policy. New portable consent uses Agreement v3.

Agreement v2 Model

The JACS header still owns document identity, versioning, authorship signatures, hashes, registration, files, and visibility. The agreement body owns consent:

• title, description, terms, termsFormat
• effectiveFrom, expiresAt
• parties
• signaturePolicy
• agreementSignatures
• transcript
• allPreviousVersions
• links
• controllers, owners

jacsAgreementHash is the consent hash. It changes when terms, parties, signature policy, or effective/expiry dates change. Transcript appends do not change it; signers bind the transcript state with signedTranscriptHash when transcript entries exist.

Roles

Minimal Input

{
  "title": "Refund approval",
  "description": "Agent A and Agent B agree on a bounded refund.",
  "terms": "Agent B may issue a refund up to $25 for order 123.",
  "termsFormat": "text/plain",
  "status": "proposed",
  "parties": [
    { "agentId": "00000000-0000-4000-8000-000000000001", "agentType": "ai", "role": "signer" },
    { "agentId": "00000000-0000-4000-8000-000000000002", "agentType": "human", "role": "signer" },
    { "agentId": "00000000-0000-4000-8000-000000000003", "agentType": "ai", "role": "notary" }
  ],
  "signaturePolicy": {
    "partyQuorum": "all",
    "witnessRequired": 0,
    "notaryRequired": 1,
    "minimumStrength": "classical"
  },
  "controllers": [
    "00000000-0000-4000-8000-000000000001",
    "00000000-0000-4000-8000-000000000002",
    "00000000-0000-4000-8000-000000000003"
  ]
}

Rust Core API

Rust core is the source of truth for Agreement v2 behavior. Binding surfaces call into the same helpers.

#![allow(unused)]
fn main() {
use jacs::agreements::v2::{
    create,
    sign,
    verify,
    AgreementV2Role,
    CreateAgreementV2,
};

let agreement = create(&agent, input)?;
let signed = sign(&agent, &agreement.raw, AgreementV2Role::Signer)?;
let report = verify(&agent, &signed.raw)?;

assert!(report.mathematical_checks_valid);
assert!(!report.valid);
assert!(!report.policy_accepted);
}

Use mutations for successor versions instead of editing JSON by hand. The helpers maintain jacsAgreementHash, jacsPreviousVersion, allPreviousVersions, status, and signature invalidation.

CLI

jacs-compat agreement-v2 create --input agreement-input.json > agreement.json
jacs-compat agreement-v2 sign --agreement agreement.json --role signer > signed.json
jacs-compat agreement-v2 verify --agreement signed.json

Branch handling is also in core and exposed through the CLI:

jacs-compat agreement-v2 detect-conflict --base base.json --left left.json --right right.json
jacs-compat agreement-v2 merge-transcript --base base.json --left left.json --right right.json
jacs-compat agreement-v2 resolve-conflict --base base.json --previous left.json --side-branch right.json --mutation resolution.json

Transcript-only branches can auto-merge. Terms conflicts require an explicit successor mutation.

Legacy Sidecar Agreements

Legacy v1; new work should use Agreement v2. See Migrating from v1 agreements.

The older jacsAgreement field on arbitrary signed documents remains available for simple countersignature workflows:

jacs-compat document create-agreement -f ./document.json -i agent1-uuid,agent2-uuid
jacs-compat document sign-agreement -f ./document-with-agreement.json
jacs-compat document check-agreement -f ./document-with-agreement.json

Use the legacy sidecar only when you need "these keys signed this existing payload (without authenticated consent policy)." Use Agreement v2 when you need standalone terms, lifecycle, transcript evidence, notary signatures, branch handling, or portable SDK parity.

Exporting as a Verifiable Credential

With the agreements feature, SimpleAgent::export_agreement_v2_as_vc(agreement_json) projects an Agreement-v2 document into a VC 2.0 credential with an ecdsa-jcs-2019 Data Integrity proof (ES256 compatibility key, Multikey verification method). It requires the agreement-vc binding scope — content scopes are never auto-issued — and never mutates the native agreement. See the Agreement v2 Developer Guide for the full flow.

See Also

• Agreement v2 Developer Guide
• CLI Agreements
• Working with Documents

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

DNS-Based Agent Verification

Native JACS can publish a raw public-key fingerprint in DNS and retrieve a candidate key over HTTPS. Discovery is opt-in and does not enroll a trusted identity. Start with the key discovery and verification guide for the current source's configuration, exact-version lookup and verifier coverage. Portable jacs CLI/MCP verification continues to require explicit key material.

Generate publication material

With an existing native identity configured in jacs.config.json:

jacs-compat agent dns --domain agent.example.com --encoding hex
jacs-compat agent dns --domain agent.example.com --provider aws
jacs-compat agent dns --domain agent.example.com --provider azure
jacs-compat agent dns --domain agent.example.com --provider cloudflare

These commands print records or provider-specific publication material. Review and publish it through your DNS operator; the CLI does not change DNS itself. --ttl selects the record TTL. The default digest encoding is standard Base64; --encoding hex selects hexadecimal. Both encode SHA-256 of the raw public key.

The record at _v1.agent.jacs.agent.example.com has this shape:

v=jacs; jacs_agent_id=<agent-uuid>; alg=SHA-256; enc=hex; jac_public_key_hash=<64-hex-raw-key-digest>

An optional uri=https://... identifies supported key-discovery JSON on the publisher origin or an explicitly configured registry's exact-version endpoint. Without it, the native resolver requests the domain's /.well-known/jacs-pubkey.json. The Rust build_agent_dns_txt_with_uri helper validates this field. Publish only public material. A served current-key document cannot substitute for the exact historical version named by an older signature.

Configure verification

export JACS_KEY_RESOLUTION=local,dns
export JACS_ALLOW_DNS=true
export JACS_ALLOW_REMOTE_KEY_FETCH=true
export JACS_DNS_KEY_DOMAINS=agent.example.com

A native v2 envelope may also contain a signed agentDomain routing hint. Until the complete signature verifies, treat that field as untrusted input. The fetched key must match the DNS fingerprint, signed key reference, algorithm and identity/version. A domain claim alone is not a trusted identity.

For the configured native agent's own validation:

JACS_ALLOW_DNS=true jacs-compat agent verify --require-strict-dns

Strict mode requires an actual Secure DNSSEC proof; an AD flag by itself does not establish it. Configure zone signing and the registrar's DS delegation first. Do not silently weaken strict policy to make a failed check pass. The DNS trust guide explains the remaining boundaries.

Rotation and troubleshooting

Agent-specific lookup accepts multiple agents and overlapping fingerprints in the same TXT record set. It rejects conflicting URIs for one agent/fingerprint. Retain historical key endpoints where your application needs old documents, and enforce revocation independently. TTLs, caches and retention policy govern your overlap; there is no fixed universal wait period.

Use dig +dnssec _v1.agent.jacs.agent.example.com TXT to inspect records; requesting DNSSEC records with dig alone does not prove validation succeeded. On a mismatch, check the decoded raw key and selected agent/version rather than comparing the encoded DNS digest to jacsSignature.publicKeyHash. Their hash contracts differ.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

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.16.1"

Feature Flags

[dependencies]
jacs = { version = "=0.16.1", features = ["otlp-logs", "otlp-metrics", "otlp-tracing"] }

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

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 (requires the native s3 feature)
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` resolve in the native document service.

Error Handling

Fallible APIs return Result; the exact error type depends on the API (including JacsError and storage-specific errors):

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

    Ok(())
}

Next Steps

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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

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.16.1", features = ["otlp-logs", "otlp-metrics", "otlp-tracing"] }

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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Node.js Installation

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

@hai.ai/jacs is a native Node.js package. Browser applications use @hai.ai/jacs-wasm.

Requirements

• Node.js 20 or newer.
• Published addons: macOS x64/arm64, Linux x64/arm64 for glibc and Linux x64 for musl. No native Windows addon is published; WSL needs a matching Linux build.
• Source builds with NAPI-RS CLI 3: Node ^20.17.0, ^22.13.0 or >=23.5.0, plus Rust 1.97 and a platform C toolchain.

Installation

npm install --save-exact @hai.ai/jacs@0.16.1

The package includes prebuilt bindings. Its optional install script downloads a checksummed portable CLI; npm install --ignore-scripts skips that download. The library remains usable without the CLI. See the package README for details.

Verify Installation

Save as test.mjs and run node test.mjs:

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

await jacs.quickstart({ name: 'my-agent', domain: 'my-agent.example.com' });
const signed = await jacs.signMessage({ hello: 'world' });
const result = await jacs.verify(signed.raw);
if (!result.valid) throw new Error('signature verification failed');
console.log('Verified 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.

New identities default to pq2025 (ML-DSA-87), without classical fallback. Ed25519 is an explicit compatibility choice.

Package Structure

TypeScript declarations are included. Choose the API for your application:

See the simple API, instance usage and API reference for method signatures and async/sync variants.

Configuration and storage

Use quickstart() to create a persistent identity, or load(configPath) for an existing one. See configuration for paths, password sources and environment settings, and storage for backends. Selecting a backend in config does not add a missing build feature; AWS/S3 requires a custom source build with the Rust s3 feature enabled.

Troubleshooting

• Check node --version and match the addon's OS, architecture and libc. npm rebuild cannot supply an unpublished target. For a custom build, use make build-jacsnpm from the repository root; see the native development guide.
• Keep config and key directories private and writable by the signing user. For decryption errors, check the password source before replacing keys.
• Use .mjs or "type": "module" for examples with import and top-level await. Type declarations ship with the package; use a module-resolution mode compatible with your Node/TypeScript toolchain.

Next Steps

• MCP integration
• Express, Koa, LangChain.js and Vercel AI SDK
• Examples

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Simplified API

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

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.

Async and synchronous methods

The standard JacsAgent I/O methods and simple signing helpers are async. Selected operations also provide Sync variants. Standalone verification, trust helpers and several low-level JacsSimpleAgent methods are synchronous; check the API signature for the method you call.

// 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 syncSigned = jacs.signMessageSync({ action: 'approve' });

Quick Start

Quickstart creates or loads an identity. Run this example as an ES module (.mjs); name and domain are required:

import * as jacs from '@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: '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

The following operations offer async and explicit synchronous variants:

Synchronous helpers (some call the native binding; no suffix is 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". User-facing choices: "ed25519", "pq2025"; "ring-Ed25519" is accepted as a legacy alias.

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}`);

// Explicit compatibility identity in a separate config directory
const compatibilityInfo = await jacs.quickstart({
  name: 'my-agent',
  domain: 'my-agent.example.com',
  algorithm: 'ed25519',
  configPath: './compatibility/jacs.config.json',
});

// Sync variant (blocks event loop)
const syncInfo = jacs.quickstartSync({
  name: 'my-agent',
  domain: 'my-agent.example.com',
  algorithm: 'ed25519',
  configPath: './compatibility/jacs.config.json',
});

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 syncInfo = 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 syncSigned = 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 (synchronous native verification)

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

HTTP protocol helpers (JacsSimpleAgent instances)

The module-level async API focuses on durable documents. Request-bound HTTP auth and signed event methods live on the synchronous instance class:

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

const agent = JacsSimpleAgent.ephemeral('ed25519');
const body = '{"action":"approve"}';
const authorization = agent.buildRequestAuthHeader(
  'POST',
  'https://api.example.com/v1/jobs?mode=strict',
  body,
  'jobs-api',
);

const envelope = agent.signResponse(JSON.stringify({ decision: 'allow' }));
const signerId = JSON.parse(envelope).jacsSignature.agentID;
const keys = JSON.stringify({ [signerId]: agent.getPublicKeyPem() });
const verified = JSON.parse(agent.unwrapSignedEvent(envelope, keys));
if (!authorization.startsWith('JACS v2.') || !verified.verified) {
  throw new Error('protocol verification failed');
}

• buildRequestAuthHeader(method, url, body, audience) binds the normalized method, absolute URL including query, exact UTF-8 body bytes, audience, signer/key, issue time, and nonce. Stringify the final request body first and send it unchanged.
• signResponse(payloadJson) returns a 2.0.0 envelope whose jacs-response-v2 signature covers payload and all metadata.
• unwrapSignedEvent(eventJson, serverKeysJson) returns JSON containing verified data, signerId, timestamp, algorithm, and documentId. Plain/unsigned input, legacy payload-only envelopes, unknown signers, and any mutation throw; it never successfully returns verified: false.

The server key map is the application's configured trust decision. Signature verification proves possession of the corresponding key, not a real-world identity by itself.

Legacy no-argument buildAuthHeader() remains available for compatibility and emits a WARN. Migrate both peers to v2; strict deployments can reject the legacy method with JACS_REJECT_UNBOUND_AUTH_HEADER=true. See Security.

signText(path, options?)

Append a YAML-bodied JACS signature block to the end of a markdown or text file. The file content (everything before the first signature block) is preserved byte-for-byte; multi-signer files are unordered. Returns a Promise containing the signing report.

Parameters: path (string): file to sign in place; options may contain noBackup?: boolean (default false).

Returns: Promise<any> — the native signing report

Throws: MarkerCollision error if the file contains a column-zero -----BEGIN JACS SIGNATURE----- outside a valid block.

await jacs.signText('README.md');

verifyText(path, options?)

Verify all signature blocks in a text file. Permissive by default — missing signatures are a typed status, not an error.

Parameters:

• path (string)
• options (object, optional): { strict?: boolean, keyDir?: string }. When strict is true, the Promise rejects with a MissingSignature-bearing error if the file is unsigned. keyDir is a directory of <signer_id>.public.pem files used in addition to the local trust store.

Returns: Promise<VerifyTextResult> — .status is 'signed' | 'missing_signature' | 'malformed'; .signers lists per-signer outcomes.

const result = await jacs.verifyText('README.md');
console.log(result.status);  // 'signed'

// Strict — Promise rejects on missing signature
try {
  await jacs.verifyText('UNSIGNED.md', { strict: true });
} catch (err) {
  if (/MissingSignature/.test(err.message)) {
    console.log('not signed');
  } else {
    throw err;
  }
}

See the inline text signing guide for the full feature set.

signImage(path, out, options?)

Embed a JACS signature inside a PNG, JPEG, or WebP image. The signature lives in a metadata chunk (PNG iTXt / JPEG APP11 / WebP XMP).

Parameters:

• path (string): input image
• out (string): output path
• options (object, optional): { robust?: boolean, refuseOverwrite?: boolean }. robust opts in to LSB fallback for PNG/JPEG (off by default; WebP deferred). refuseOverwrite rejects with AlreadySigned if the input already carries a signature.

Returns: Promise<any> — the native signing report

await jacs.signImage('photo.png', 'signed.png');

verifyImage(path, options?)

Verify the embedded signature on an image. Same permissive / strict model as verifyText.

Parameters: as for verifyText.

Returns: Promise<VerifyImageResult> — .status is 'valid' | 'invalid' | 'missing_signature'; .signerId, .signedAt, .algorithm populated when valid.

const v = await jacs.verifyImage('signed.png');
console.log(v.status);  // 'valid'

See the media signing guide for the full feature set.

extractMediaSignature(path, options?)

Extract the embedded signature payload without verifying it.

Parameters:

• path (string)
• options (object, optional): { rawPayload?: boolean } — when true, returns the base64url wire form instead of decoded JSON.

Returns: Promise<string | null> — serialized JSON by default, base64url when rawPayload: true, or null when no payload is found.

const payloadJson = await jacs.extractMediaSignature('signed.png');
if (payloadJson !== null) console.log(JSON.parse(payloadJson));
// Extraction does not verify the signature.

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(documentKey, newDocumentData, attachments?, embed?)

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

Parameters:

• documentKey (string): Stored document key, ${jacsId}:${jacsVersion}
• 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 documentKey = `${doc.jacsId}:${doc.jacsVersion}`;
const updated = await jacs.updateDocument(documentKey, doc);

exportAgent()

Export the current agent document for sharing or inspection.

Returns: string -- The agent JSON document (synchronous, 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. Synchronous, no suffix needed.

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

Returns: string

getWellKnownJson()

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

Returns: object

getPublicKey()

Get the loaded agent's public key in PEM format. Synchronous, 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

import * as jacs from '@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

Use the simplified API inside a real MCP SDK handler. The MCP chapter shows ListToolsRequestSchema and CallToolRequestSchema, transport setup, and peer policy. A tool can return signed.raw as MCP text content, but signing a tool result alone does not authenticate the transport or authorize its caller.

Error Handling

import * as jacs from '@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);
}

// With a loaded agent, invalid documents return valid:false; setup failures may throw
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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Basic Usage

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

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

Async and synchronous methods

The standard JacsAgent I/O methods and simple signing helpers are async. Selected operations also provide Sync variants. Standalone verification, trust helpers and several low-level JacsSimpleAgent methods are synchronous; check the API signature for the method you call.

// 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 syncDoc = 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 an identity with quickstart first. A configuration only points to existing keys and an agent document; writing placeholder IDs does not initialize an agent. A generated config contains fields like:

{
  "$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": "pq2025",
  "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

// Use a complete document previously created and stored by this agent.
const updatedData = JSON.parse(signedDocument);
const documentKey = `${updatedData.jacsId}:${updatedData.jacsVersion}`;
updatedData.title = 'Updated Proposal';
updatedData.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

The methods below inspect the legacy jacsAgreement sidecar. Its participant, role and quorum policy is not authenticated; complete, policy_authenticated and policy_accepted remain false. Agreement v2 also provides inspection, not application consent or execution permission. See Agreement v2.

Create an Agreement

// Add agreement requiring multiple agent signatures
const documentWithAgreement = await agent.createAgreement(
  signedDocumentJson,
  [JSON.parse(agent.exportAgent()).jacsId], // local signer for this example
  '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 agentDocument = JSON.parse(agent.exportAgent());
agentDocument.jacsAgentType = 'hybrid';
const updatedAgentJson = await agent.updateAgent(JSON.stringify(agentDocument));

Sign External Agent

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

Request/Response Signing

These legacy instance methods sign generic documents. They do not bind HTTP request context or authorize a route. Use request-bound HTTP credentials for that purpose. 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
  'pq2025',            // 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 generic proposal document
  const proposal = {
    title: 'Project Proposal',
    description: 'Q1 development plan',
    budget: 50000
  };

  const signedProposal = await agent.createDocument(JSON.stringify(proposal));
  console.log('Document created');

  // Verify the document
  if (await agent.verifyDocument(signedProposal)) {
    console.log('Document signature valid');
  }

  // Create a sidecar for signature inspection
  const proposalWithAgreement = await agent.createAgreement(
    signedProposal,
    [JSON.parse(agent.exportAgent()).jacsId],
    'Do you approve this proposal?'
  );

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

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

  // Hash some data for reference
  const proposalHash = hashString(signedProposal);
  console.log('Document hash:', proposalHash);
}

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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

MCP Integration (Node.js)

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

MCP is the primary integration for external model clients. For the portable server, install jacs-cli and run jacs mcp; it starts in verify-only mode. See the current MCP guide. The separate native compatibility server is jacs-compat mcp from jacs-cli-compat.

Inside a Node application, choose between signed tool results on ordinary MCP and the JACS transport extension. Signing an output does not authenticate its recipient or authorize a tool call.

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

Signed tool results on ordinary MCP

This ES module (server.mjs) registers a read-only echo tool that signs its result. The SDK uses request schemas, not string method names, for handlers:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { JacsClient } from '@hai.ai/jacs/client';

const client = await JacsClient.quickstart({
  name: 'echo-server', domain: 'mcp.local',
  configPath: './server/jacs.config.json',
});
const server = new Server(
  { name: 'signed-echo', version: '1.0.0' },
  { capabilities: { tools: {} } },
);
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: 'echo', description: 'Return signed echo data',
    inputSchema: {
      type: 'object', properties: { message: { type: 'string' } },
      required: ['message'], additionalProperties: false,
    },
  }],
}));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name !== 'echo') throw new Error('Unknown tool');
  const message = request.params.arguments?.message;
  if (typeof message !== 'string') throw new Error('message must be a string');
  const signed = await client.signMessage({ echo: message });
  return { content: [{ type: 'text', text: signed.raw }] };
});
await server.connect(new StdioServerTransport());

An ordinary MCP client can call this tool. Its relying application must verify the returned document against its own trusted keys before using the contents. Keep stdio diagnostics on stderr; stdout carries protocol messages only.

Signed transport between JACS peers

Both peers must use the JACS transport wrapper. This is a local-only extension, not a transparent way to connect arbitrary MCP clients. The implementation rejects localOnly: false.

Provision each peer's identity and verification key through a trusted channel before connecting. Set one exact expectedPeerAgentId, or an intentional allowedPeerAgentIds allowlist, on each wrapper. A missing policy rejects incoming authenticated messages. An optional expectedPeerPublicKeyHash additionally pins the key for one exact peer.

Replace the final connection in the server above with:

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

const expectedPeerAgentId = process.env.JACS_EXPECTED_CLIENT_ID;
if (!expectedPeerAgentId) throw new Error('Configure the trusted client agent ID');
const transport = createJACSTransportProxy(
  new StdioServerTransport(), client, 'server', { expectedPeerAgentId },
);
await server.connect(transport);

The matching client wraps its StdioClientTransport the same way, using role 'client' and the trusted server ID. Use separate configuration directories for server and client so quickstart does not reload the same identity. Load verification keys into the local trust/key store before starting; these options select an allowed identity, they do not fetch its key.

When only an existing config path is available:

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

const transport = await createJACSTransportProxyAsync(
  baseTransport, './client/jacs.config.json', 'client',
  { expectedPeerAgentId: trustedServerId },
);

The synchronous factory takes a loaded JacsClient or JacsAgent, never a config path. Signing, signature checks, peer checks and message dispatch fail closed by default. Do not use allowUnsignedFallback or dangerouslyAllowAnyValidSigner when authenticated peer identity is required. Signatures provide integrity and key possession, not encryption. Application permissions and replay policy remain separate from signature validity.

Registering compatibility tools

registerJacsTools(server, client) installs the Node compatibility tool list and SDK handlers on a low-level Server. It replaces the list/call handlers, so do not combine it with the echo handlers above. The helper includes signing, agreement and trust-store mutations as well as inspection; it does not inherit the portable server's verify-only profile. Expose only operations authorized for your callers.

For a selected tool list, use getJacsMcpToolDefinitions() and handleJacsMcpToolCall(client, name, args) behind your own SDK schema handlers and allowlist. Some setup/registry entries are stubs; listing an operation does not establish that it implements the full Rust server contract.

For a model already running inside Node, see LangChain.js or Vercel AI SDK. For protocol-wide concepts, see the native MCP guide.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

LangChain.js Integration

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

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 13 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_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

Signed wrappers fail closed by default: signing failures withhold the output. The explicit allowUnsignedOutput: true compatibility option permits unsigned fallback; strict: true overrides it. Tool-operation error reporting is separate:

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

Examples In This Repo

• archive/native/jacsnpm/examples/langchain/basic-agent.ts
• archive/native/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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Vercel AI SDK

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

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. Use the nonstreaming generateText path with a compatible V3 provider. The current streaming path has an SDK shape limitation described below.

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;                    // Enforce signing; override unsigned-output opt-ins
  maxBufferedStreamBytes?: number;     // Default 1 MiB; maximum 16 MiB
  metadata?: Record<string, unknown>;  // Extra metadata in provenance records
}

Streaming limitation

Use generateText for this guide. The current stream adapter reads text-delta chunks from a textDelta property and throws if it is absent. The repository tests supply that mocked shape; they do not qualify actual provider streams. The package declares broad optional ai >=4 and @ai-sdk/provider >=1 peer ranges rather than a tested pinned V3 provider. Do not assume a provider emitting a different delta shape is supported.

When compatible chunks are supplied, the adapter buffers the whole stream, signs it, and only then releases chunks. The default bound is 1 MiB; maxBufferedStreamBytes can raise it to at most 16 MiB. Overflow or signing failure withholds output. Explicit unsigned/post-hoc options weaken that boundary and are not a remedy for an incompatible SDK shape.

Tool Call Signing

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

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

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

// Tool results are signed when fed back into a subsequent model step
console.log(providerMetadata?.jacs?.text?.signed);
console.log(providerMetadata?.jacs?.toolResults?.signed);

Provenance Record

Each signed output produces a ProvenanceRecord:

interface SignedProvenanceRecord {
  signed: true;
  documentId: string;    // JACS document ID
  agentId: string;       // Signing agent's ID
  timestamp: string;     // ISO 8601 timestamp
  signedDocument: string; // Full portable signed JACS document
  metadata?: Record<string, unknown>;
}

ProvenanceRecord is a union of that signed shape and an unsigned failure shape (signed: false, empty IDs/timestamp, and error). Unsigned records are only returned through explicit compatibility options. Verify signedDocument and compare its signed output and metadata; the other fields alone are not proof.

Access records from providerMetadata.jacs:

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

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

Strict Mode

Signing fails closed by default: a failed signature withholds the output. strict: true also overrides explicit unsigned-output compatibility opt-ins. Do not enable unsigned or post-hoc streaming options when signed output is required:

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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Express Middleware

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

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. Response signing intercepts res.json() when enabled.

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

interface JacsMiddlewareOptions {
  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/invalid bodies through (default: false)
  authReplay?: boolean | {   // Signed-body freshness/deduplication (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): A supplied 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 });
  }
});

Signed-body replay checks

This option adds freshness and deduplication to signed bodies. It does not authorize a route or bind the HTTP method, URL, body bytes, and audience. Use request-bound authorization and a configured signer policy for that boundary:

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.

Response signing fails closed by default: errors withhold the unsigned body. The explicit allowUnsignedOutput: true compatibility option relaxes this; strict: true overrides that option. Routes requiring a signed body should also reject a missing payload, since body verification is not route authorization.

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' }));

// Routes requiring signed document bodies
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 and separate config directories per route group. Quickstart loads an existing config before creating an identity; changing name alone does not create another agent:

const adminClient = await JacsClient.quickstart({
  name: 'admin-agent',
  domain: 'admin.example.com',
  configPath: './admin/jacs.config.json',
  algorithm: 'pq2025',
});
const userClient = await JacsClient.quickstart({
  name: 'user-agent',
  domain: 'user.example.com',
  configPath: './user/jacs.config.json',
  algorithm: 'pq2025',
});

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 @hai.ai/jacs/http adapter calls removed root-module helpers. Migrate to the maintained adapter:

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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Koa Middleware

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

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

interface JacsKoaMiddlewareOptions {
  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/invalid bodies through (default: false)
  authReplay?: boolean | {   // Signed-body freshness/deduplication (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: A supplied 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 defined and not a Buffer, it is signed (including JSON scalars) before the response is sent.

Signed-body replay checks

This option adds freshness and deduplication to signed bodies. It does not authorize a route or bind the HTTP method, URL, body bytes, and audience. Use request-bound authorization and a configured signer policy for that boundary:

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.

Response signing fails closed by default: errors withhold the unsigned body. The explicit allowUnsignedOutput: true compatibility option relaxes this; strict: true overrides that option. Routes requiring a signed body should also reject a missing payload, since body verification is not route authorization.

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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

HTTP Signing and Verification

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

HTTP integration has two separate jobs: verifying signed documents and binding authorization to the actual request. The maintained Express and Koa adapters verify document bodies and optionally sign responses. They do not implement request-bound authorization. The old @hai.ai/jacs/http adapter calls removed root-module helpers; migrate to those framework adapters instead.

Request-bound credentials

Use the synchronous JacsSimpleAgent instance API. Run this client as an ES module (.mjs), with an existing client configuration and a trusted server-key map provisioned independently of the response:

import { readFile } from 'node:fs/promises';
import { JacsSimpleAgent } from '@hai.ai/jacs';

const agent = JacsSimpleAgent.load('./client/jacs.config.json');
const serverKeysJson = await readFile('./trusted-server-keys.json', 'utf8');
const url = 'https://api.example.com/v1/jobs?mode=strict';
const body = JSON.stringify({ action: 'inspect', jobId: '42' });
const authorization = agent.buildRequestAuthHeader('POST', url, body, 'jobs-api');

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: authorization },
  body,
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const event = JSON.parse(agent.unwrapSignedEvent(await response.text(), serverKeysJson));
console.log(event.data);

The key map is a JSON object mapping expected server agent IDs to trusted PEM public keys. Do not construct it from an unverified response. The credential binds method, absolute URL including query, exact body bytes, audience, signer/key, issue time, and nonce. Send the final body unchanged.

The server must verify the same request context with a trusted key, enforce its caller policy, and atomically consume the nonce before executing work. Neither a generic signed body nor the legacy buildAuthHeader() provides that binding. See request-bound HTTP authorization for the server contract.

Signed response events

A server with an initialized JacsSimpleAgent creates the v2 envelope with:

const envelope = agent.signResponse(JSON.stringify({ result: 42 }));

unwrapSignedEvent(envelope, serverKeysJson) verifies the complete envelope, including payload and metadata. It throws on unsigned input, legacy payload-only envelopes, unknown signers, and mutations. Its result contains verified, data, signerId, timestamp, algorithm, and documentId. Verification alone does not consume an event for replay prevention or bind it to an outstanding request; enforce those application constraints before use.

A signature proves possession of the selected key and integrity of the signed scope. Real-world identity, authorization, freshness, and permitted use come from the verifier's trust and application policies. Signatures do not encrypt the payload; use HTTPS for transport confidentiality.

Signed document bodies

For document exchange, use JacsClient.signMessage() and verify() or the framework adapters. Configure sender trust and route authorization separately. Express's authReplay and Koa's matching option add freshness and in-process deduplication for signed bodies; they do not bind method, URL, or audience.

• Express middleware: jacsMiddleware and req.jacsPayload
• Koa middleware: jacsKoaMiddleware and ctx.state.jacsPayload
• MCP integration: signed messages between configured peers
• Simplified API: documents and transport helper reference

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

API Reference

Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.

Native API reference for the @hai.ai/jacs Node.js package.

Installation

npm install @hai.ai/jacs

Async and synchronous methods

The standard JacsAgent I/O methods and simple signing helpers are async. Selected operations also provide Sync variants. Standalone verification, trust helpers and several low-level JacsSimpleAgent methods are synchronous; check the API signature for the method you call.

// 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 syncDoc = 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 syncAgentJson = 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 on success. Invalid documents can reject/throw; handle errors rather than relying on false.

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

Legacy sidecar API for mathematical signature inspection. The report keeps complete, policy_authenticated, and policy_accepted false: participant and role policy are not authenticated. Agreement v2 is also inspection-only; see its guide before interpreting reports.

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., "artifact", "result")
• 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' }),
  'artifact'
);

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(...fields)

Create a JACS configuration JSON string using the positional arguments below. This does not generate keys or create an agent. Never persist a private-key password in the generated configuration.

Parameters:

• jacsUseSecurity (string, optional)
• jacsDataDirectory (string, optional)
• jacsKeyDirectory (string, optional)
• jacsAgentPrivateKeyFilename (string, optional)
• jacsAgentPublicKeyFilename (string, optional)
• jacsAgentKeyAlgorithm (string, optional)
• jacsPrivateKeyPassword (legacy slot; leave undefined)
• jacsAgentIdAndVersion (string, optional)
• jacsDefaultStorage (string, optional)

Returns: string -- Configuration as JSON string

HTTP integration

Use jacsMiddleware from @hai.ai/jacs/express or jacsKoaMiddleware from @hai.ai/jacs/koa for signed document bodies. The old /http adapter calls removed root helpers. Request-bound authorization and pinned event verification use JacsSimpleAgent instance methods; see HTTP.

MCP module

createJACSTransportProxy(transport, loadedClientOrAgent, role, peerPolicy)
createJACSTransportProxyAsync(transport, configPath, role, peerPolicy)

The first returns JACSTransportProxy; the second returns a Promise after loading the agent. role is 'client' or 'server'. Configure peerPolicy.expectedPeerAgentId or peerPolicy.allowedPeerAgentIds on both ends and provision trusted verification keys. The transport is local-only. See MCP integration for actual SDK handlers, tool registration and failure behavior.

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

Root exports and legacy functions

Root exports include JacsAgent, JacsSimpleAgent, hashString, and the positional createConfig helper. Historical module-level entry points now have explicit names such as legacyLoad and legacyCreateDocument. The old jacs.load() and jacs.createDocument() globals are not exported.

Use instance methods or the separate @hai.ai/jacs/simple module:

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' }));

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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Browser WASM Package

@hai.ai/jacs-wasm is the browser WebAssembly package for JACS. Use it when a web page needs to create a browser-local JACS agent, sign JSON, verify signed JACS documents, or collect multi-party agreement signatures without calling a backend service.

Published 0.16.1: See the release inventory for provenance and installed-browser checks. Later source APIs require a separate release record; use a local build for current checkout behavior.

For Node.js server applications, use the native @hai.ai/jacs package instead. @hai.ai/jacs-wasm is browser-only: no filesystem access, no DNS trust lookup, no MCP server, and no CLI process.

Install

npm install --save-exact @hai.ai/jacs-wasm@0.16.1

To build this checkout instead:

git clone https://github.com/HumanAssisted/JACS.git
cd JACS
make build-wasm
# From your consuming project:
npm install /absolute/path/to/JACS/jacs-wasm/pkg

Bundlers must be able to load an ES module plus the generated jacs_wasm_bg.wasm asset. The source package is smoke-tested with Vite and Chromium.

Quick Start

import { createEphemeral, initJacsWasm } from "@hai.ai/jacs-wasm";

await initJacsWasm();

const agent = await createEphemeral(); // pq2025; no classical fallback
const signed = agent.signMessageJson(JSON.stringify({ hello: "world" }));
const result = JSON.parse(agent.verifyJson(signed));

console.log(result.valid); // true

initJacsWasm() is idempotent. The async constructors also initialize the module, so applications can call createEphemeral, importEncryptedAgent, importEncryptedAgentFiles, or createVerifier directly.

Public API

Constructors:

createEphemeral(algorithm?: "ed25519" | "pq2025" | "es256"): Promise<CoreAgentHandle>
importEncryptedAgent(materialJson: string, password: string): Promise<CoreAgentHandle>
importEncryptedAgentFiles(files: EncryptedAgentFiles, password: string): Promise<CoreAgentHandle>
createVerifier(publicKeyBase64: string, algorithm: "ed25519" | "pq2025" | "es256"): Promise<CoreAgentHandle>

importEncryptedAgentFiles is shaped for browser file pickers:

type EncryptedAgentFiles = {
  configText: string;
  agentText: string;
  publicKeyBytes: Uint8Array;
  encryptedPrivateKeyBytes: Uint8Array;
};

The wrapper infers the algorithm from the raw public key length: 32 bytes for ed25519, 2592 bytes for pq2025, and 65-byte uncompressed SEC1 for explicit ES256 compatibility. New identities default to pq2025.

Core handle methods:

agent.signMessageJson(dataJson: string): string
agent.verifyJson(signedJson: string): string
agent.verifyWithKeyJson(
  signedJson: string,
  publicKeyBase64: string,
  algorithm: "ed25519" | "pq2025" | "es256",
): string
agent.exportAgent(): string
agent.getPublicKeyBase64(): string
agent.algorithm(): "ed25519" | "pq2025" | "es256"
agent.isUnlocked(): boolean
agent.clearSecrets(): void
agent.metrics(): string

clearSecrets() zeroes the in-memory private key. Signing then fails with a Locked error, while verification continues to work.

Agreement signature inspection

Browser callers can collect and inspect v1 sidecar signatures. This local example constructs both handles and pins their actual IDs and keys before receiving an agreement. In an application, obtain the signer-key mapping through independently trusted enrollment, never from the submitted document.

import { createEphemeral, createVerifier, createAgreementJson } from "@hai.ai/jacs-wasm";

const alice = await createEphemeral();
const bob = await createEphemeral();
const aliceId = JSON.parse(alice.exportAgent()).jacsId;
const bobId = JSON.parse(bob.exportAgent()).jacsId;
const trustedSigners = [
  { agentId: aliceId, publicKeyBase64: alice.getPublicKeyBase64(), algorithm: alice.algorithm() },
  { agentId: bobId, publicKeyBase64: bob.getPublicKeyBase64(), algorithm: bob.algorithm() },
];
const verifier = await createVerifier(alice.getPublicKeyBase64(), alice.algorithm());
const agreement = createAgreementJson(
  JSON.stringify({ action: "review", version: "1.2.3" }),
  JSON.stringify([aliceId, bobId]),
  "Have you reviewed this release?",
  "Signature inspection example",
);
const signedByAlice = alice.signAgreementJson(agreement, "reviewer");
const signedByBoth = bob.signAgreementJson(signedByAlice, "reviewer");
const outcome = JSON.parse(
  verifier.verifyAgreementJson(signedByBoth, JSON.stringify(trustedSigners)),
);
console.log(outcome);

The v1 signature does not authenticate participant, role or quorum policy; role can be edited without invalidating its signature. The report's mathematical outcomes are not consent, policy acceptance or permission to execute. Missing signer keys are reported per signer. Keep application acceptance policy separate from these inspection results.

Browser Persistence

localStore wraps window.localStorage and stores values under the jacs: namespace.

import { localStore } from "@hai.ai/jacs-wasm";

localStore.saveEncryptedAgent("alice", encryptedMaterialJson);
localStore.saveDocument("doc-1", signed);

const restored = localStore.loadEncryptedAgent("alice");
const keys = localStore.listKeys();

localStore.remove("doc-1");
localStore.clearAll();

saveEncryptedAgent refuses obvious plaintext secrets, top-level or nested password-like fields, and raw private-key-shaped payloads. The browser package should persist encrypted agent material and signed documents only.

Workers

Post-quantum key generation can block the main thread. The worker subpath moves key generation and signing to a Web Worker:

import {
  createEphemeralInWorker,
} from "@hai.ai/jacs-wasm/worker";

const workerAgent = await createEphemeralInWorker("pq2025");
const signed = await workerAgent.signMessage(JSON.stringify({ hello: "world" }));

Observability

Browsers do not expose stdout or a Prometheus endpoint for package code. @hai.ai/jacs-wasm exposes per-handle counters instead:

const snapshot = JSON.parse(agent.metrics());
// { signCount, verifyCount, lastSignDurationMs, lastVerifyDurationMs }

For local debugging, set globalThis.JACS_WASM_DEBUG = true before a sign, verify, or clearSecrets call. Debug logging is off by default.

Security Notes

WebAssembly memory is visible to JavaScript running on the same page. That means any XSS, compromised dependency, malicious browser extension, or third-party script on the origin can potentially inspect key material while an agent is unlocked.

Use @hai.ai/jacs-wasm for browser-local signing when that risk is acceptable. For hardware-backed or high-assurance signing, use a hardware key, secure-enclave-backed WebCrypto flow, or server-side signer. Call clearSecrets() as soon as the user is done signing.

Local Build and Chromium Smoke Test

Install the Rust WASM target once:

rustup target add wasm32-unknown-unknown
cargo install wasm-pack

Build the package and run the browser smoke fixture:

make build-wasm

cd jacs-wasm/examples/vite-smoke
npm install
npx playwright install chromium
npx playwright test --project=chromium

The Chromium smoke test builds the Vite app, serves the static output, loads it in Chromium, creates an ephemeral @hai.ai/jacs-wasm agent, signs a JSON payload, verifies it, and waits for SMOKE OK in the page output.

CI runs the same browser path in the WASM PR and release workflows.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Python Installation

Install the published native package:

python -m pip install jacs==0.16.1

Published 0.16.1 wheels support Python 3.11–3.14 on macOS arm64/x86_64, Linux arm64/x86_64 glibc, and Linux x86_64 musl; this checkout has the same Python requirement. A compatible wheel needs no Rust compiler. See the release inventory for platform evidence; later source changes are not automatically in the wheel.

Try signing

from jacs.client import JacsClient

client = JacsClient.ephemeral()
signed = client.sign_message({"message": "Hello from Python"})
assert client.verify(signed.raw).valid

For an identity that survives process restarts:

client = JacsClient.quickstart(name="my-agent", domain="my-agent.example.com")
signed = client.sign_message({"message": "Persistent identity"})
assert client.verify(signed.raw).valid

New agents default to pq2025 (ML-DSA-87). Quickstart loads an existing configuration or creates encrypted keys. Preserve the password through a host secret source or keychain; an automatically generated password may otherwise survive only in-process. See native password bootstrap.

Optional integrations

python -m pip install "jacs[mcp]"
python -m pip install "jacs[fastapi]"
python -m pip install "jacs[langchain,langgraph]"
python -m pip install "jacs[anthropic]"
python -m pip install "jacs[a2a-server]"

Install only the extras you need. The a2a extra adds no dependencies; a2a-server supplies FastAPI and Uvicorn.

CLI and source builds

The Python jacs command downloads and caches the matching CLI release on first use and verifies its SHA-256. Importing the library downloads nothing. Unsupported platforms fail; no musl CLI archive is published. Alternatively install the portable CLI with cargo install jacs-cli and start its verify-only MCP server with jacs mcp. If the Python shim shadows Cargo's binary, invoke the binary in Cargo's bin directory explicitly.

Native configuration commands belong to the separate compatibility CLI: cargo install jacs-cli-compat installs jacs-compat. Prefer the Python quickstart above to create a Python agent.

For source builds, follow the native development guide from the complete repository. Native bindings use a separate Cargo workspace.

Continue with Basic Usage, MCP, or Framework Adapters.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Simplified API

jacs.simple provides one process-wide session for signing and verification.

Quick Start

Create or load a persistent agent:

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

Use jacs.simple for one agent per process, JacsClient for independent agents, and lower-level JacsAgent when you need direct document/config control.

API Reference

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

Create or load a persistent agent. See the Quick Start above for password handling; call this before signing or verifying.

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". User-facing choices: "ed25519", "pq2025"; "ring-Ed25519" is accepted as a legacy alias.
• 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="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

HTTP protocol helpers (SimpleAgent instances)

The module-level API focuses on durable documents. Request-bound HTTP auth and signed event helpers live on the instance-based native SimpleAgent:

import json
from jacs import SimpleAgent

agent, _ = SimpleAgent.ephemeral()  # default pq2025
body = '{"action":"approve"}'
authorization = agent.build_request_auth_header(
    "POST",
    "https://api.example.com/v1/jobs?mode=strict",
    body,
    "jobs-api",
)

envelope = agent.sign_response(json.dumps({"decision": "allow"}))
signer_id = json.loads(envelope)["jacsSignature"]["agentID"]
keys = json.dumps({signer_id: agent.get_public_key_pem()})
verified = json.loads(agent.unwrap_signed_event(envelope, keys))
assert authorization.startswith("JACS v2.")
assert verified["verified"] is True
assert verified["data"]["decision"] == "allow"

• build_request_auth_header(method, url, body="", audience="hai.ai") binds the normalized method, absolute URL including query, exact UTF-8 body bytes, audience, signer/key, issue time, and nonce. Serialize the final request body before calling it and transmit that string unchanged.
• sign_response(payload_json) returns a 2.0.0 envelope whose jacs-response-v2 signature covers payload and all metadata.
• unwrap_signed_event(event_json, server_keys_json) returns JSON containing verified data, signerId, timestamp, algorithm, and documentId. Plain/unsigned input, legacy payload-only envelopes, unknown signers, and any mutation raise; it never successfully returns verified: false.

server_keys_json is a map from signer ID to a pinned base64 key or PEM string. It represents the application's configured trust decision. Cryptographic success proves possession of that key, not a real-world identity by itself.

Legacy no-argument build_auth_header() remains available for compatibility and emits a WARN. Migrate both peers to v2; strict deployments can reject the legacy method with JACS_REJECT_UNBOUND_AUTH_HEADER=true. See Security.

sign_text(path)

Append a YAML-bodied JACS signature block to the end of a markdown or text file. The file content (everything before the first signature block) is preserved byte-for-byte; multi-signer files are unordered.

Parameters: path (str): file to sign in place

Returns: SignTextResult

Raises: RuntimeError if the file contains a column-zero -----BEGIN JACS SIGNATURE----- outside a valid block — see the inline-text-signing guide for documented workarounds.

jacs.sign_text("README.md")

verify_text(path, *, strict=False, key_dir=None)

Verify all signature blocks in a text file. Permissive by default — missing signatures are a typed status, not an error.

Parameters:

• path (str)
• strict (bool, keyword-only): when True, raises MissingSignatureError if the file is unsigned. Default False.
• key_dir (str, keyword-only): directory of <signer_id>.public.pem files used in addition to the local trust store.

Returns: VerifyTextResult — .status is 'signed' | 'missing_signature' | 'malformed'; .signatures lists per-signer outcomes.

result = jacs.verify_text("README.md")
print(result.status)  # 'signed'

# Strict — missing signature raises
try:
    jacs.verify_text("UNSIGNED.md", strict=True)
except MissingSignatureError:
    print("not signed")

See the inline text signing guide for the full feature set.

sign_image(input_path, output_path, *, robust=False, refuse_overwrite=False)

Embed a JACS signature inside a PNG, JPEG, or WebP image. The signature lives in a metadata chunk (PNG iTXt / JPEG APP11 / WebP XMP).

Parameters:

• input_path (str): input image
• output_path (str): required output path.
• robust (bool, keyword-only): opt-in LSB embedding fallback for PNG/JPEG (off by default; WebP deferred).
• refuse_overwrite (bool, keyword-only): raise an error if the input already carries a signature.

Returns: SignImageResult

jacs.sign_image("photo.png", "signed.png")

verify_image(path, *, strict=False, key_dir=None)

Verify the embedded signature on an image. Same permissive / strict model as verify_text.

Parameters: as for verify_text.

Returns: VerifyImageResult with .status, optional .signer_id and .format. Status values include valid, invalid_signature, hash_mismatch, missing_signature, key_not_found, unsupported_format and malformed.

v = jacs.verify_image("signed.png")
print(v.status)  # 'valid'

See the media signing guide for the full feature set.

extract_media_signature(path, *, raw_payload=False)

Extract the embedded signature payload without verifying it.

Parameters:

• path (str)
• raw_payload (bool, keyword-only): emit the base64url wire form instead of decoded JSON. Default False.

Returns: Optional[str]: a JSON string, or the base64url wire form when raw_payload=True; None if no signature is present.

import json

payload = jacs.extract_media_signature("signed.png")
if payload is not None:
    print(json.loads(payload))  # Extraction alone does not verify the payload.

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["description"] = "Hybrid signing agent"

# 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.

The original must be available in the agent's document store. no_save controls file export; it does not prevent in-memory storage.

Parameters:

• document_id (str): Full jacsId:jacsVersion lookup key
• new_document_data (dict|str): Complete updated document, preserving its headers
• 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
import jacs as native

# Use a native stored document and its full id:version lookup key.
agent = native.JacsAgent()
agent.load("./jacs.config.json")
original = json.loads(agent.create_document(
    json.dumps({"content": {"status": "pending"}}), None, None, False, None, None
))
document_key = f"{original['jacsId']}:{original['jacsVersion']}"
original["content"]["status"] = "approved"
updated = json.loads(agent.update_document(document_key, json.dumps(original), None, None))
print(f"New version: {updated['jacsVersion']}")
print(f"Previous: {updated['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=jacs; ...".

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

These result types provide attributes for common operations:

See the type definitions for constructors, defaults and aliases, and error handling for exceptions. Signer timestamps are claims, not an independent time authority.

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:
    print(f"Payment verified from: {verification.signer_id}")
    print(json.loads(signed.raw))  # Inspect the document only after verification.
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"
agent_doc["description"] = "AI signing 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}")

# With an agent loaded and strict mode disabled, inspect result.valid.
# An unloaded agent raises AgentNotLoadedError; strict mode raises VerificationError.
result = jacs.verify("invalid json")
if not result.valid:
    print(f"Verification errors: {result.errors}")

See Also

• Basic Usage - Independent JacsClient instances
• API Reference - Client APIs and native argument requirements
• MCP Integration - Model Context Protocol

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Python Basic Usage

Use JacsClient for independent agents, or jacs.simple for one process-wide session.

Sign and verify

from jacs.client import JacsClient

client = JacsClient.quickstart(name="my-agent", domain="my-agent.example.com")
signed = client.sign_message({"event": "tool-result", "answer": 42})
result = client.verify(signed.raw)
if not result.valid:
    raise ValueError(result.errors)
print(result.signer_id, signed.payload)

Quickstart loads an existing config or creates encrypted keys with pq2025. See password bootstrap for preserving access across process restarts. To load explicitly:

client = JacsClient(config_path="./jacs.config.json", strict=True)

With strict=True, verification failures raise VerificationError; with strict mode disabled, inspect result.valid and result.errors. Configuration and signing errors still raise.

Verification authenticates bytes under the resolved key. Separately require the expected signer, trusted identity binding, allowed action and freshness before executing an operation.

Save and exchange signed JSON

from pathlib import Path

Path("signed.json").write_text(signed.raw, encoding="utf-8")
received = Path("signed.json").read_text(encoding="utf-8")
result = client.verify(received)
if not result.valid:
    raise ValueError(result.errors)

Send the complete signed.raw, including signature and metadata. To verify another agent, configure its public key under your trust policy. A key embedded in a submission or fetched from a URL is not an identity endorsement.

Files and public identity

signed_file = client.sign_file("report.pdf", embed=True)
assert client.verify(signed_file.raw).valid
agent_json = client.export_agent()
public_key_pem = client.get_public_key()

The file must already exist. Embedding carries its bytes; embed=False records a reference/hash. Apply an external-file verification policy when receiving referenced files. Share public identity material through an authenticated channel.

Independent agents

alice = JacsClient.quickstart(
    name="alice", domain="alice.example.com", config_path="./alice/jacs.config.json"
)
bob = JacsClient.quickstart(
    name="bob", domain="bob.example.com", config_path="./bob/jacs.config.json"
)

For short-lived tests, JacsClient.ephemeral() keeps its identity in memory. Do not assume separate ephemeral agents can resolve one another's public keys.

Agreements and integrations

Legacy create_agreement(), sign_agreement() and check_agreement() inspect sidecar evidence; inspection cannot establish application consent. Agreement v2 is available on jacs.simple and native SimpleAgent; its valid and policyAccepted remain false even when mathematicalChecksValid is true.

See MCP, Framework Adapters, and the API reference for direct native calls.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

MCP Integration (Python)

For the primary ready-made JACS tool server, install jacs-cli and run jacs mcp (ordinary stdio MCP, verify-only by default). The native Python integrations below serve different purposes. Install their optional dependency:

python -m pip install "jacs[mcp]==0.16.1"

When building this checkout, use its mcp extra and source Python requirements.

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.

The signed local HTTP transport requires JACS wrappers at both endpoints and trusted peer keys. A stock MCP client cannot consume its signed carriers directly. Registering tools on ordinary FastMCP instead preserves ordinary MCP transport; it does not add caller authentication or permission to sign.

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
• Clients must pin the expected server agent ID; servers must allowlist client agent IDs
• stdio is rejected because it bypasses the HTTP signing middleware
• JSON POST and response bodies default to a 2 MiB hard limit (JACS_MCP_MAX_MESSAGE_BYTES)
• strict=True is about config loading and failure behavior, not an opt-in to security

A valid signature proves possession of a key, not that the signer is the intended peer. The peer-ID policy below is what binds that proof to your deployment. An optional expected_peer_public_key_hash also pins one exact server key. On the server, the agent-ID allowlist is combined with JACS trust/key resolution; operators must maintain rotation and revocation policy for those allowed identities.

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",
    allowed_peer_agent_ids=["CLIENT_AGENT_ID"],
)

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

mcp.run(transport="sse")

If you already have a FastMCP instance:

from fastmcp import FastMCP
from jacs.mcp import JACSMCPServer

mcp = JACSMCPServer(
    FastMCP("Secure Server"),
    "./jacs.config.json",
    allowed_peer_agent_ids=["CLIENT_AGENT_ID"],
)

app = mcp.http_app(transport="sse")

2. Secure A FastMCP Client

from jacs.mcp import JACSMCPClient

client = JACSMCPClient(
    "http://localhost:8000/sse",
    "./jacs.config.json",
    expected_peer_agent_id="SERVER_AGENT_ID",
    # Optional stronger rotation policy:
    # expected_peer_public_key_hash="SERVER_PUBLIC_KEY_HASH",
)

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

To accept any valid signer without authenticating which peer signed, use the separate dangerous compatibility switch:

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

This is proof-of-possession only and is not peer authentication. To allow fully unsigned fallback explicitly:

client = JACSMCPClient(
    "http://localhost:8000/sse",
    "./jacs.config.json",
    expected_peer_agent_id="SERVER_AGENT_ID",
    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/file signing, verification, legacy sidecar agreement inspection, agent-info, public sharing and media helpers; it does not register an audit tool. A2A and trust helpers are separate opt-in registrations. Expose signing and trust mutations only to callers authorized by your host policy. Agreement inspection does not establish application consent.

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

jacs_tool, jacs_middleware(), and JacsSSETransport refuse unsigned output when no agent is loaded or signing fails. The dangerous allow_unsigned_fallback=True option restores legacy passthrough explicitly. Authenticated transport messages use a schema-valid JSON-RPC carrier whose params.envelope is a complete portable-v2 JACS document. Requests receive a fresh unpredictable wire ID per session, and responses with unknown IDs fail closed, preventing a signed response from being transplanted into another client session.

Example Paths In This Repo

• archive/native/jacspy/examples/mcp/server.py
• archive/native/jacspy/examples/mcp/client.py
• archive/native/jacspy/examples/mcp_server.py
• archive/native/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, or FastAPI boundaries
• you do not need MCP clients to connect from outside the app

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

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[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 archive/native/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:

• Signing failures and invalid signed POST bodies fail closed by default
• sign_responses=False or verify_requests=False to narrow the behavior
• a2a=True exposes discovery documents cached at middleware initialization; use the A2A serving guide for renewal-aware routes

Request verification only examines POST JSON objects containing jacsSignature. Unsigned, empty and non-JSON bodies, and other HTTP methods, continue to the application even with strict=True. This middleware verifies documents; it does not authenticate every request or bind the signature to HTTP method, URL and audience. Enforce required authentication separately.

Legacy compatibility options are explicit and dangerous:

• allow_unsigned_output=True permits raw output after signing fails
• allow_unverified_passthrough=True permits unverifiable input to continue
• allow_plain_signature_fallback=True permits an attestation request to downgrade to a plain signature, dropping attestation claims

strict=True always disables all three fallbacks. Do not use these options at a trust boundary unless the caller separately marks the data as unsigned or unverified.

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,
)

This checks freshness and duplicate signatures only for verified signed POST bodies. Its replay cache is local to the middleware instance; it is lost on restart and is not shared across workers or replicas. It does not make unsigned requests fail closed. See the request authentication and replay guide for a complete authentication boundary.

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}

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

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Python API Reference

Start with Basic Usage. Native arguments accepting None are not necessarily optional at the call site.

JacsClient

from jacs.client import JacsClient

client = JacsClient.quickstart(name="my-agent", domain="my-agent.example.com")
signed = client.sign_message({"message": "hello"})
assert client.verify(signed.raw).valid

The constructor's algorithm argument does not create an agent; select an algorithm through a factory. New agents default to pq2025. verify() accepts JSON, a dict or SignedDocument; strict mode raises on verification failures, otherwise inspect valid and errors.

See the client source for trust-store, attestation, media and A2A helpers.

Result types

raw aliases raw_json, agent_id aliases signer_id, and timestamp aliases signed_at on SignedDocument. Signer timestamps are claims; verification does not grant permission to act.

Low-level JacsAgent

Every argument below without a default must be supplied, even when its value is None. Native operation errors normally raise RuntimeError; Python argument conversion can raise TypeError.

import json
from jacs import JacsAgent

agent = JacsAgent()
agent.load("./jacs.config.json")
document = agent.create_document(
    json.dumps({"jacsDocument": {"type": "message", "content": {"answer": 42}}}),
    None,   # custom_schema
    None,   # outputfilename
    True,   # no_save
    None,   # attachments
    None,   # embed
)
assert agent.verify_document(document)
assert agent.verify_agent(None)

create_document.attachments accepts an optional string through the native attachment parser; update_document.attachments accepts an optional list of paths. Use sign_file() for the common single-file workflow.

Document updates require the original to be available in the agent's document store. Parse the complete document, derive jacsId:jacsVersion, modify its application fields, and submit the complete replacement. no_save controls file export; it does not mean the document is absent from the in-memory store.

Legacy agreement parameters are exactly agentids and agreement_fieldname on JacsAgent. JacsClient.create_agreement() uses agent_ids and field_name instead. Inspection reports include verified_signature_count, pending, and mathematical_checks_valid; complete and policy_accepted remain false. Never infer consent from them.

Configuration helper

jacs.create_config() returns configuration JSON and does not create keys. All nine arguments are required, though each accepts None:

create_config(jacs_use_security, jacs_data_directory, jacs_key_directory,
              jacs_agent_private_key_filename, jacs_agent_public_key_filename,
              jacs_agent_key_algorithm, jacs_private_key_password,
              jacs_agent_id_and_version, jacs_default_storage)

Prefer JacsClient.quickstart() for setup. Keep passwords in host secret handling rather than examples, logs or persisted config.

Native SimpleAgent

SimpleAgent provides instance-based Agreement v2, request authentication, signed events and public human-approval verification. See the simplified API guide and native binding source. Do not assume methods on one native class exist on the other.

See MCP, Framework Adapters, and Python examples.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Go (jacsgo) Installation and Quick Start

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

Go bindings are supported native packages; Python and Node.js have broader framework adapter coverage. For the primary verify-only MCP server, install jacs-cli and run jacs mcp. The extended native server is jacs-compat mcp from jacs-cli-compat; Go MCP examples are demos.

Install

Version 0.16.1 publishes the Go module and matching macOS/Linux native libraries. go get alone does not provide the CGo library. In a module that imports github.com/HumanAssisted/JACS/jacsgo:

go get github.com/HumanAssisted/JACS/jacsgo@v0.16.1
go mod vendor
go run github.com/HumanAssisted/JACS/jacsgo/cmd/jacsgo-install@v0.16.1 -version v0.16.1

The installer writes a checksum-verified library into the vendored package's build/ directory. See the Go package guide for platform coverage, provenance and source builds. From the full repository, make build-jacsgo builds the current native library. Published artifacts do not imply that later source APIs have been released.

Minimal Sign + Verify

Create an agent first (CLI: jacs-compat quickstart --name my-agent --domain my-agent.example.com, or programmatically with jacs.Create(name, opts) 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-compat quickstart --name my-agent --domain my-agent.example.com")
	}

	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 and A2A helpers also have package-level wrappers. Request authentication and signed-event helpers require an agent instance; use JacsSimpleAgent for the shared simple binding contract.

Request authentication and signed events

For the cross-language simple contract, use JacsSimpleAgent:

agent, _, err := jacs.EphemeralSimpleAgent(nil) // default pq2025
if err != nil {
	log.Fatal(err)
}
defer agent.Close()

body := []byte(`{"action":"approve"}`)
authorization, err := agent.BuildRequestAuthHeader(
	"POST",
	"https://api.example.com/v1/jobs?mode=strict",
	body,
	"jobs-api",
)
if err != nil {
	log.Fatal(err)
}

envelope, err := agent.SignResponse(`{"decision":"allow"}`)
if err != nil {
	log.Fatal(err)
}

BuildRequestAuthHeader binds method, absolute URL including query, exact body bytes, audience, signer/key, issue time, and nonce. SignResponse creates a fully bound 2.0.0 response envelope. Verify an incoming envelope with UnwrapSignedEvent(eventJSON, serverKeysJSON), where serverKeysJSON is a JSON map from signer ID to a pinned base64 key or PEM string. Plain events, unknown signers, legacy payload-only envelopes, and mutations return errors without releasing data.

The key map is a configured trust decision. A valid signature proves key possession, not a real-world identity by itself. Both JacsAgent.BuildAuthHeader() and JacsSimpleAgent.BuildAuthHeader() retain the legacy no-argument form and emit a warning. Use BuildRequestAuthHeader for v2; deployments can reject the legacy form with JACS_REJECT_UNBOUND_AUTH_HEADER=true. See the security guide.

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:

• archive/native/jacsgo/examples/mcp/main.go for MCP-style request/response signing
• archive/native/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).

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

JSON Schemas

JACS schemas now describe a small portable signing surface instead of many narrow workflow document types. The core model is a generic signed JSON document: canonical JSON bytes, a common header, cryptographic signatures, signer identity, hashes, optional files, and optional agreement semantics.

Application-specific payloads belong in the document body or in a custom schema layered on top of the header schema.

Preserved Schemas

Document and Agent Schemas

Component Schemas

Configuration Schema

Schema Locations

Schemas are available as HTTPS URLs and local files:

https://hai.ai/schemas/header/v1/header.schema.json
https://hai.ai/schemas/agent/v1/agent.schema.json
https://hai.ai/schemas/agreement/v2/agreement.schema.json
https://hai.ai/schemas/components/signature/v1/signature.schema.json
https://hai.ai/schemas/components/agreement/v1/agreement.schema.json
https://hai.ai/schemas/components/files/v1/files.schema.json
https://hai.ai/schemas/jacs.config.schema.json

Generic Signed Documents

Every signed document includes a $schema field. Generic payloads use the header schema directly:

{
  "$schema": "https://hai.ai/schemas/header/v1/header.schema.json",
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsType": "document",
  "jacsLevel": "artifact",
  "content": {
    "invoice_id": "INV-001",
    "amount": 100.0
  }
}

Custom schemas may extend the header when an integration needs stronger payload validation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.com/schemas/invoice.schema.json",
  "allOf": [
    { "$ref": "https://hai.ai/schemas/header/v1/header.schema.json" },
    {
      "type": "object",
      "properties": {
        "content": {
          "type": "object",
          "required": ["invoice_id", "amount"]
        }
      }
    }
  ]
}

Agreements

Native Agreement v2 represents standalone terms, parties and signature records, but its verifier reports mathematical checks only: valid=false, policyAccepted=false, overallScope=consent_signatures_only. Legacy jacsAgreement v1 countersignatures likewise do not authenticate participant, role, quorum, question or context policy.

For authenticated portable consent policy, use Agreement v3. Application authorization remains separate. The native agreement reference documents compatibility inspection.

HAI Extensions

The schema's custom hai property categorizes fields as meta, base or agent. These annotations participate in native schema-driven hashing; they do not supply an authorization policy.

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Agent Schema

The Agent Schema defines signed identity documents for entities that can sign and verify JACS documents. Agents are cryptographic identities, not catalogs of services or contact records.

Schema Location

https://hai.ai/schemas/agent/v1/agent.schema.json

Overview

Agent documents describe:

• Identity and versioning
• Agent type
• Optional DNS-based verification domain
• Public-key and signature metadata

Capabilities for A2A interoperability are represented in A2A Agent Cards instead of the JACS identity schema.

Agent Types

The jacsAgentType field classifies the agent:

Agent Fields

DNS Verification

Agents can link to a domain for DNSSEC-validated verification:

{
  "jacsAgentDomain": "example.com"
}

The domain should have a DNS TXT record at _v1.agent.jacs.example.com. containing the agent's public key fingerprint.

Example

{
  "$schema": "https://hai.ai/schemas/agent/v1/agent.schema.json",
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsType": "agent",
  "jacsOriginalVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsOriginalDate": "2024-01-15T10:30:00Z",
  "jacsLevel": "artifact",
  "jacsAgentType": "ai",
  "jacsAgentDomain": "agent.example.com",
  "jacsSignature": {
    "agentID": "550e8400-e29b-41d4-a716-446655440000",
    "agentVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "date": "2024-01-15T10:30:00Z",
    "signature": "base64-encoded-signature...",
    "publicKeyHash": "sha256-hash-of-public-key",
    "signingAlgorithm": "pq2025",
    "fields": ["jacsId", "jacsVersion", "jacsAgentType", "jacsAgentDomain"]
  },
  "jacsSha256": "document-hash..."
}

See Also

• Document Schema
• DNS-Based Verification
• A2A Interoperability

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Document Schema

The Document Schema is the generic header/signature wrapper for JACS documents. It is intentionally payload-agnostic: applications can sign arbitrary JSON content while preserving the same hashing, signature, agreement, and verification contracts across languages.

Schema Location

https://hai.ai/schemas/header/v1/header.schema.json

Overview

The header schema provides:

• Unique document and version identifiers
• Version history through previous-version references
• Cryptographic signatures and hashes
• Optional file attachments
• Optional multi-party agreements

Core Fields

Document Level

Signatures

jacsSignature contains the signing agent, timestamp, algorithm, public key hash, fields signed, and signature bytes.

{
  "jacsSignature": {
    "agentID": "550e8400-e29b-41d4-a716-446655440000",
    "agentVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "date": "2024-01-15T10:30:00Z",
    "signature": "base64-encoded-signature-string",
    "publicKeyHash": "sha256-hash-of-public-key",
    "signingAlgorithm": "pq2025",
    "fields": ["jacsId", "jacsVersion", "jacsType", "content"]
  }
}

Agreements

Any signed document can include jacsAgreement for multi-party approval.

{
  "jacsAgreement": {
    "agentIDs": [
      "agent-1-uuid",
      "agent-2-uuid"
    ],
    "question": "Do you approve this payload?",
    "context": "Deployment approval",
    "quorum": 2,
    "signatures": []
  },
  "jacsAgreementHash": "hash-of-content-at-agreement-time"
}

File Attachments

Documents can include file attachments using jacsFiles:

{
  "jacsFiles": [
    {
      "mimetype": "application/pdf",
      "path": "./documents/contract.pdf",
      "embed": false,
      "sha256": "file-content-hash"
    }
  ]
}

Complete Example

{
  "$schema": "https://hai.ai/schemas/header/v1/header.schema.json",
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsType": "document",
  "jacsVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsOriginalVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "jacsOriginalDate": "2024-01-15T10:30:00Z",
  "jacsLevel": "artifact",
  "content": {
    "title": "Sample Document",
    "body": "This is arbitrary signed JSON content."
  },
  "jacsSignature": {
    "agentID": "550e8400-e29b-41d4-a716-446655440000",
    "agentVersion": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "date": "2024-01-15T10:30:00Z",
    "signature": "signature-base64...",
    "publicKeyHash": "public-key-hash...",
    "signingAlgorithm": "pq2025",
    "fields": ["$schema", "jacsId", "jacsType", "jacsVersion", "content"]
  },
  "jacsSha256": "document-hash..."
}

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Config File Schema

This page documents the jacs.config.json schema fields. For a comprehensive configuration guide including observability setup, storage backends, zero-config quickstart, and production patterns, see the Configuration Reference.

Schema Location

https://hai.ai/schemas/jacs.config.schema.json

Minimal Configuration

Use quickstart() to create and sign a persistent config. A creation template must include the schema's six required settings:

{
  "$schema": "https://hai.ai/schemas/jacs.config.schema.json",
  "jacs_data_directory": "./jacs_data",
  "jacs_key_directory": "./jacs_keys",
  "jacs_agent_private_key_filename": "jacs.private.pem.enc",
  "jacs_agent_public_key_filename": "jacs.public.pem",
  "jacs_agent_key_algorithm": "pq2025",
  "jacs_default_storage": "fs"
}

This unsigned template does not load an existing identity. Existing-agent configs also need the generated identity/version and valid config signature; do not reconstruct them by editing this template.

Fields

Configuration Options

Key Configuration

jacs_agent_key_algorithm

Specifies the cryptographic algorithm for signing:

{
  "jacs_agent_key_algorithm": "pq2025"
}

jacs_agent_private_key_filename

Name of the private key file in the key directory:

{
  "jacs_agent_private_key_filename": "private.pem"
}

Use the filename produced by agent creation; do not rename encrypted key files independently of their config.

jacs_agent_public_key_filename

Name of the public key file:

{
  "jacs_agent_public_key_filename": "public.pem"
}

jacs_private_key_password

Supply the password through the host's JACS_PRIVATE_KEY_PASSWORD, a protected password file or the OS keychain. Do not persist plaintext passwords in JSON config. See password sources.

Storage Configuration

jacs_default_storage

Specifies where documents are stored:

{
  "jacs_default_storage": "fs"
}

jacs_data_directory

Path for storing documents and agents:

{
  "jacs_data_directory": "./jacs_data"
}

Agent Identity

jacs_agent_id_and_version

Load an existing agent by ID and version:

{
  "jacs_agent_id_and_version": "550e8400-e29b-41d4-a716-446655440000:f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Schema Versions

Specify which schema versions to use:

{
  "jacs_agent_schema_version": "v1",
  "jacs_header_schema_version": "v1",
  "jacs_signature_schema_version": "v1"
}

DNS Configuration

DNS compares a published fingerprint with the selected native key; strict mode also validates DNSSEC. A domain does not independently authorize an agent.

jacs_agent_domain

The domain used for DNS fingerprint checks. Configure it during agent creation, then publish the required TXT record.

jacs_dns_validate

Controls whether native verification attempts DNS, with the domain and explicit CLI options determining the effective behavior. See the CLI DNS options.

jacs_dns_strict

When true, shared native key discovery (the dns key source) requires a Secure DNSSEC proof, as does Agent::set_dns_strict(true). Agent verification does not read this field: use jacs-compat agent verify --require-strict-dns or AgentBuilder::dns_strict(true) to require strict validation there. A verified DNS claim also forces strict validation.

jacs_dns_required

Controls whether a domain and successful DNS validation are required. Select CLI flags or builder settings explicitly when this is part of the application's policy.

Security

jacs_keychain_backend

OS keychain backend for password storage. Controls whether JACS looks up the private key password from the OS credential store.

{
  "jacs_keychain_backend": "auto"
}

Override with env var: JACS_KEYCHAIN_BACKEND=disabled

See OS Keychain Configuration for full details.

jacs_use_security

Enable strict security features:

{
  "jacs_use_security": "1"
}

Values: "0", "1", or "false", "true"

Observability Fields

The observability object supports logs, metrics, and tracing sub-objects. For full details on all destinations, sampling options, and production patterns, see the Configuration Reference.

Environment Variables

Configuration can be overridden with environment variables:

See Also

• Configuration Reference - Full configuration guide with examples
• JSON Schemas Overview - Schema architecture
• Observability (Rust API) - Rust observability API
• Observability & Monitoring Guide - Structured events, OTEL collector setup

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

JACS Attestation vs. Other Standards

JACS occupies a unique position as an agent-layer attestation framework. This page compares JACS with related standards and explains when to use them together.

Comparison Table

JACS vs. in-toto / SLSA

Domain difference: in-toto and SLSA focus on build provenance -- proving that a software artifact was built by a specific builder from specific source code. JACS focuses on runtime agent actions -- proving that a specific agent performed a specific action with specific evidence.

Interoperability: JACS exports attestations as DSSE (Dead Simple Signing Envelope) documents, the same format used by in-toto v1.0+. This means:

• A JACS attestation can include an in-toto predicate type URI
• SLSA verifiers can validate the DSSE envelope structure
• JACS and in-toto attestations can coexist in the same verification pipeline

When to use both: If your workflow includes both software builds (use SLSA/in-toto for build provenance) and AI agent actions (use JACS for runtime attestation), you can link them via derivation chains.

JACS vs. Sigstore / cosign

Domain difference: Sigstore provides signing infrastructure (Fulcio CA, Rekor transparency log) and cosign is a tool for signing container images and artifacts. JACS provides its own signing with decentralized identity.

Key difference: Sigstore's keyless signing relies on centralized OIDC identity providers and a public transparency log. JACS uses self-managed key pairs and does not require any centralized infrastructure.

When to use both: Sigstore for container image signing in CI/CD pipelines. JACS for AI agent action signing at runtime. A planned Sigstore bundle verification adapter (N+2) would let JACS attestations reference Sigstore signatures as evidence.

JACS vs. SCITT

Most overlap. SCITT (Supply Chain Integrity, Transparency and Trust) defines a centralized transparency service for recording signed statements about artifacts.

Key difference: SCITT requires a transparency log (centralized notary). JACS is fully decentralized and offline-capable. JACS verification works without contacting any server.

Complementary use: JACS signs and attests. SCITT logs. An organization could use JACS to create signed attestations and then submit them to a SCITT transparency log for auditability, getting the benefits of both decentralized creation and centralized discoverability.

JACS vs. IETF RATS / EAT

Layer difference: RATS (Remote ATtestation procedureS) and EAT (Entity Attestation Token) focus on hardware and platform attestation -- proving that a device or execution environment is in a known-good state. JACS fills the software agent layer above hardware.

Alignment opportunity: JACS claim names could align with IANA-registered EAT claim types where they overlap. A JACS attestation could reference a RATS attestation result as evidence, creating a trust chain from hardware to agent.

IETF drafts of interest:

• draft-huang-rats-agentic-eat-cap-attest-00 -- Capability attestation for agents, directly aligned with JACS claims model
• draft-messous-eat-ai-00 -- EAT profile for AI agents
• draft-jiang-seat-dynamic-attestation-00 -- Dynamic attestation for runtime assertions

JACS vs. CSA Agentic Trust Framework

The Cloud Security Alliance's Agentic Trust Framework defines progressive trust levels that map directly to JACS's trust model:

When to Use JACS

Use JACS when you need:

• Agent identity that works without PKI/CA infrastructure
• Non-repudiable action logging for AI agent workflows
• Multi-agent authorization with quorum (M-of-N approval)
• Offline verification without centralized services
• Evidence-backed trust that goes beyond simple signing
• Post-quantum readiness for long-lived agent identities

When to Use JACS Alongside Other Tools

Native library reference. Extended CLI examples use jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.

Security Model

JACS verifies signed data under selected keys. Applications establish identity, trust and authorization around that cryptographic evidence.

Security Model (v0.6.0+)

• Passwords: The private key password can be provided via JACS_PRIVATE_KEY_PASSWORD environment variable, JACS_PASSWORD_FILE, or the OS keychain (macOS Keychain / Linux Secret Service). It is never stored in config files.
• Keys: New private-key envelopes use AES-256-GCM with Argon2id. Legacy PBKDF2 envelopes remain readable; public keys and config may be stored on disk.
• Path validation: All paths built from untrusted input (e.g. publicKeyHash, filenames) are validated via require_relative_path_safe() to prevent directory traversal. This single validation function is used in data and key directory path builders and the trust store. It rejects empty segments, ., .., null bytes, and Windows drive-prefixed paths.
• Trust ID canonicalization: Trust-store operations normalize canonical agent docs (jacsId + jacsVersion) into a safe UUID:VERSION_UUID identifier before filesystem use, preserving path-safety checks while supporting standard agent document layout.
• Filesystem schema policy: Local schema loading is disabled by default and requires JACS_ALLOW_FILESYSTEM_SCHEMAS=true. When enabled, schema paths must remain within configured roots (JACS_DATA_DIRECTORY and/or JACS_SCHEMA_DIRECTORY) after normalized/canonical path checks.
• Network endpoint policy: Registry verification requires HTTPS for JACS_REGISTRY_URL (legacy alias: HAI_API_URL). Localhost HTTP is allowed for local testing only.
• Strict JSON ingress: Raw JSON crossing a signing, verification, hashing, schema, or protocol boundary must pass the shared jacs-core strict decoder. Duplicate decoded object names are rejected recursively before a serde_json::Value can collapse them; escape-equivalent names are duplicates, while repeated array elements remain valid.
• No secrets in config: Config files must not contain passwords or other secrets. The example config (jacs.config.example.json) does not include jacs_private_key_password.
• Dependency auditing: Run cargo audit (Rust), npm audit (Node.js), or pip audit (Python) to check for known vulnerabilities.

Core Security Principles

1. Cryptographic Identity

Every JACS agent has a unique cryptographic identity:

• Key Pair: Each agent possesses a private/public key pair
• Agent ID: Unique UUID identifying the agent
• Public Key Hash: SHA-256 hash of the public key for verification

{
  "jacsSignature": {
    "agentID": "550e8400-e29b-41d4-a716-446655440000",
    "publicKeyHash": "sha256-of-public-key",
    "signingAlgorithm": "pq2025"
  }
}

Native signing defaults to post-quantum pq2025 (ML-DSA-87 / FIPS-204). Explicit ed25519 creation is supported and emits the canonical ring-Ed25519 label. Routine rotation preserves the current algorithm; Ed25519 can explicitly upgrade to pq2025, while PQ-to-Ed25519 downgrade is rejected.

2. Document Integrity

Signatures and hashes protect the signed bytes under the selected public key. Version IDs do not establish a complete history, and signer-supplied timestamps do not prove an independent signing time or real-world authorship.

Security Audit (audit())

JACS provides a read-only security audit that checks configuration, directories, secrets, trust store, storage, quarantine/failed files, and optionally re-verifies recent documents. It does not modify state.

Purpose: Surface misconfiguration, missing keys, unexpected paths, and verification failures in one report.

Options (all optional):

• config_path: Path to jacs.config.json (default: 12-factor load)
• data_directory / key_directory: Override paths
• recent_verify_count: Number of recent documents to re-verify (default 10, max 100)

Return structure: AuditResult with overall_status, risks (list of AuditRisk), health_checks (list of ComponentHealth), summary, checked_at, and optional quarantine_entries / failed_entries.

Rust:

#![allow(unused)]
fn main() {
use jacs::audit::{audit, AuditOptions};

let result = audit(AuditOptions::default())?;
println!("{}", jacs::format_audit_report(&result));
}

Python:

import jacs.simple as jacs

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

Node.js:

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

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

Available in the language bindings for local diagnostics and automation.

Threat Model

Protected Against

Trust Assumptions

1. Private keys are kept secure
2. Cryptographic algorithms are sound
3. DNS infrastructure (when used) is trustworthy

Replay Store Deployment

The default replay backend is a bounded, atomic, process-local Moka cache. It accepts exactly one concurrent use of a nonce within one process and is suitable for local development or a genuinely single-process service.

Multi-replica production services must install an implementation of the Rust ReplayStore trait backed by a shared atomic primitive (for example Redis SET key value NX EX ttl or a database unique insert), then set JACS_REQUIRE_SHARED_REPLAY_STORE=true. With that setting JACS fails closed if the installed backend reports itself as process-local or returns an error. The library never silently falls back to memory after a shared-store failure.

Replay decisions emit structured events without nonce contents and increment jacs_replay_checks_total{backend,outcome}. Use JACS_PAYLOAD_MAX_REPLAY_SECONDS to configure the default payload window. For an accepted future-skewed payload, JACS retains its nonce through the signed timestamp plus that window, not merely for a fixed interval from verification.

Remote JWKS Retrieval

A2A Agent Card verification keeps JWKS network access disabled unless JACS_ALLOW_JWKS_FETCH=true (or the broader JACS_ALLOW_NETWORK=true) is set. Even after that opt-in, JACS accepts only HTTPS origins, resolves and validates every redirect hop, rejects private/reserved IP answers, pins the validated DNS answer into the HTTP client, disables proxy resolution, allows at most three same-origin redirects, and requires a JSON Content-Type. The whole operation is limited to five seconds and 256 KiB.

Loopback HTTP remains available for deliberate local development only when both the network capability and JACS_ALLOW_PRIVATE_JWKS=true are set. Do not enable the private-JWKS override in a service that assesses Agent Cards supplied by untrusted callers.

Request-Bound HTTP Authorization

Use the request builder exposed by your API with the actual HTTP method, absolute URL, exact body bytes (empty bytes for no body), and a service-specific audience:

The resulting JACS v2... header authenticates the signer/key ID, normalized scheme/authority/path/query, SHA-256 content digest, audience, timestamp, and nonce. verify_request_auth_header requires the trusted key and the actual request context; any method, endpoint, query, body, signer, or audience substitution fails before replay state is consumed.

Build the header after the final body serialization and send those same bytes. On verification, reconstruct the absolute URL from trusted server/framework configuration rather than trusting an attacker-controlled forwarding header. The standard Rust verifier atomically consumes replay state after all other checks pass. Servers with an application-owned shared store use verify_request_auth_header_with_trusted_key_without_replay, then grant access only if an atomic insert such as Redis SET ... NX EX ... accepts the returned nonce. Use request_auth_replay_ttl(&verified_claims, max_age) for the Redis expiry (or retain it longer). A fixed max_age TTL is insufficient when the signer's accepted clock skew is positive: the credential's absolute expiry is issued_at + max_age.

The older no-argument Rust build_auth_header and equivalent legacy class methods sign only identity, time, and nonce. They remain available for source compatibility and emit a WARN because a first-use credential could be moved to a different request. The additive request-bound methods require method, URL, body, and audience and emit v2. Strict deployments can reject legacy construction with JACS_REJECT_UNBOUND_AUTH_HEADER=true.

Encrypted-Key KDF Resource Policy

V2 private-key envelopes accept only the versioned Argon2id resource profile: 8,192–19,456 KiB memory, one or two passes, and parallelism one. JACS validates these values before base64 allocation or Argon2 execution, and also caps the serialized envelope/ciphertext and enforces exact salt/nonce sizes. A policy rejection emits encrypted_key_kdf_policy_rejected at WARN and increments jacs_kdf_policy_rejections_total{kdf="Argon2id",profile="v2"}; neither signal contains passwords, key bytes, or ciphertext.

Signed Response and Event Contract

sign_response emits response envelope version 2.0.0 with signature scope jacs-response-v2. Its domain-separated signature authenticates the complete envelope except for the signature bytes themselves: payload, protocol version/type, issuer, document ID, payload hash, timestamp, signer, algorithm, public-key hash, and any additional fields. This is a protocol-specific contract; do not replace it with generic document verification or verification of data alone.

Use verify_response_json_with_key in Rust or unwrap_signed_event / unwrapSignedEvent in a native binding with a trusted map from signer ID to public key. Trusted keys may be raw bytes/base64 or canonical PEM, depending on the binding. On success the bindings return only verified data plus provenance:

{
  "data": {"decision": "allow"},
  "verified": true,
  "status": "verified",
  "signerId": "agent-id:version",
  "timestamp": "2026-07-09T12:00:00Z",
  "algorithm": "pq2025",
  "documentId": "2f1e2bdb-55f4-4c99-8f42-d45249808f4b"
}

Plain events, legacy payload-only response envelopes, unknown signers, and invalid signatures are errors. There is no successful verified: false result; callers must never dispatch an event by catching that error and reparsing its untrusted input.

These protocols authenticate control of the private key corresponding to the public key that the verifier selected. Signed agentID, name, domain, and time fields are not independent proof of a person, organization, service, or DNS identity. Establish that association through a pinned key, strict local trust configuration, or another explicitly chosen verification policy before making an authorization decision.

Signature Process

Signing a Document

1. Field Selection: Determine which fields to sign
2. Canonicalization: Serialize fields deterministically
3. Signature Generation: Sign with private key
4. Hash Computation: Compute SHA-256 of signed document

import jacs
import json

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

# Create signed document
doc = agent.create_document(json.dumps({
    'title': 'Confidential Report',
    'content': 'Sensitive data here'
}))

# Document now includes jacsSignature and jacsSha256

Verifying a Document

1. Hash Verification: Recompute hash and compare
2. Signature Verification: Verify signature with public key
3. Agent Verification: Optionally verify agent identity via DNS

is_valid = agent.verify_document(doc_json)
is_signature_valid = agent.verify_signature(doc_json)

Key Management

Compatibility key binding (P2)

An agent's ES256 ecosystem_signing key is authorized per-export by a compatibility key binding: a compatibilityKeyBinding JACS document signed by the current native root, persisted as one canonical-JSON file (jacs_keys/jacs.compat-binding.json). Lifecycle rules:

• granting or widening a scope always requires the native root's signature — the ES256 holder cannot self-escalate;
• re-issue replaces the file (latest issuedAt wins; no version chains);
• native key rotation supersedes the binding — verification fails with a "re-issue" error until a new binding is signed by the current root;
• an expired binding denies export; expiresAt: null is permitted in P2;
• default issuance grants only the identity scopes (jwks, did, a2a-agent-card, w3c-agent-identity); content scopes (ap2-mandate, agreement-vc) require an explicit re-issue.

Be precise about what this is: scope checks are a locally enforced authorization policy and an auditable delegation record for relying parties — not isolation. Both private keys live in the same directory under the same password; a compromised host is outside this model. The sound property is non-self-escalation via the native-root signature requirement.

The ES256 private key is encrypted at rest with the same AES-256-GCM + Argon2id envelope as the native root key — the post-quantum library is a signing primitive, not an encryption primitive, so compatibility keys reuse the existing audited envelope rather than inventing a PQ-encrypted key format.

Targeted content exports (P2)

Content exporters (the AP2 mandate export, the Agreement-v2-as-VC export) sign ecosystem artifacts with the ES256 compatibility key through purpose-built, schema-pinned paths — there is no generic "sign this document with algorithm X" API. Two properties matter here:

• Classical verification is not PQ trust. A stock JOSE/Data Integrity verifier can check the ES256 signature with nothing but the public key; that proves possession of the compatibility key, not the agent's native identity. Tracing the export to that root additionally requires verifying the native-root-signed compatibility key binding (jacs-compat agent export-compat-binding).
• Native documents are never mutated. Exports are derived views; the native jacsSignature keeps the agent's selected algorithm and the source document's bytes and verification are unchanged after every export. These are targeted ecosystem artifacts, not JACS projections — native documents never gain proof or other projection fields.

Exports are one-way in P2: JACS emits these artifacts, but verifying incoming AP2 mandates or third-party VCs is out of scope — use the target ecosystem's stock verifiers for that.

Key Generation

JACS generates cryptographic key pairs during agent creation:

# Keys are created in the configured key directory
jacs_keys/
├── private.pem    # Private key (keep secure!)
└── public.pem     # Public key (can be shared)

Key Protection

Encryption at Rest:

New keys use the V2 AES-256-GCM/Argon2id envelope; PBKDF2 envelopes are read-only compatibility. Never store the password in config files.

# Option 1: Environment variable (recommended for CI/servers)
export JACS_PRIVATE_KEY_PASSWORD="secure-password"

# Option 2: OS keychain (recommended for developer workstations)
jacs-compat keychain set --agent-id <YOUR_AGENT_UUID>

Important: The CLI can prompt for the password during jacs-compat init, but scripts and servers must set JACS_PRIVATE_KEY_PASSWORD as an environment variable or use the OS keychain.

OS Keychain Integration:

On macOS and Linux desktops, JACS can store and retrieve the private key password from the OS credential store, eliminating the need for environment variables or plaintext password files during day-to-day development:

• macOS: Uses Security.framework (Keychain Access)
• Linux: Uses the freedesktop.org D-Bus Secret Service API (GNOME Keyring, KDE Wallet, KeePassXC)

Each password is keyed by agent ID, so multiple agents can coexist on the same machine without overwriting each other. Store your password once with jacs-compat keychain set --agent-id <ID>, and all subsequent JACS operations will find it automatically. The password resolution order is:

1. JACS_PRIVATE_KEY_PASSWORD env var (highest priority -- explicit always wins)
2. JACS_PASSWORD_FILE / legacy .jacs_password file
3. OS keychain keyed by agent ID (lowest priority among explicit sources)

To disable keychain lookups (recommended for CI and headless environments):

export JACS_KEYCHAIN_BACKEND=disabled

Or in jacs.config.json:

{
  "jacs_keychain_backend": "disabled"
}

Keychain entries are selected by agent ID; a generic shared default entry is not the current per-agent password contract.

Security note: The OS keychain is encrypted at rest by the OS and unlocked by the user's login session. It is the same mechanism used by git, ssh-agent, docker, and other CLI tools. The keychain feature is optional and not compiled into the jacs core crate by default -- it is enabled by default in jacs-cli-compat.

Password Entropy Requirements:

JACS enforces password entropy minimums for private key encryption. Password validation is performed at encryption time, and weak passwords are rejected with helpful error messages:

• Minimum 28-bit entropy for passwords with 2+ character classes (mixed case, numbers, symbols)
• Minimum 35-bit entropy for single-character-class passwords (e.g., all lowercase)
• Entropy is calculated based on character class diversity and length
• Weak passwords result in immediate rejection during key encryption
• Error messages guide users toward stronger password choices

Example of rejected weak passwords:

• password - Too common and predictable
• 12345678 - Insufficient character diversity
• abc - Too short

File Permissions:

chmod 700 ./jacs_keys
chmod 600 ./jacs_keys/private.pem

Key Rotation

Update agent version to rotate keys:

1. Generate new key pair
2. Create new agent version
3. Sign new version with old key
4. Update configuration to use new keys

Native rotation preserves the current algorithm unless explicitly overridden. Use jacs-compat agent rotate-keys --algorithm pq2025 to upgrade Ed25519; a PQ identity cannot downgrade to Ed25519. Rotation also supersedes the ES256 compatibility key binding: re-issue it under the new native root (jacs-compat agent issue-compat-binding) before the next ecosystem export.

TLS Certificate Validation

JACS includes configurable TLS certificate validation for secure network communication.

Default Behavior (Development)

TLS certificate validation is strict by default. JACS_STRICT_TLS=false is an explicit insecure development override for the schema-fetching client; do not use it in production. Omitting the variable or setting it to true retains certificate-chain validation. This setting does not describe every network client in the repository.

Registry verification requires HTTPS (JACS_REGISTRY_URL, legacy alias HAI_API_URL); localhost HTTP is restricted to test/development endpoints.

Signature Timestamp Validation

A document's signed timestamp records the signer's claimed signing time. It is not an independently trusted timestamp or proof that a later request is fresh. JACS document and agent-identity signatures are archival: the generic signature timestamp validator does not impose a maximum age.

What the Timestamp Check Establishes

validate_signature_timestamp parses an RFC 3339 timestamp and rejects a date more than five minutes in the future relative to the verifier's clock. Older dates pass this timestamp check; they do not need to fall within five minutes of the current time. The signature, content hash and applicable trust policy must still be checked separately.

JACS_MAX_SIGNATURE_AGE_SECONDS is not a supported document-signature setting in the current runtime. Applications that need an expiration or current-authority policy must evaluate it explicitly; successful archival verification alone does not authorize a new action.

Freshness and Replay Protection

A valid timestamp does not prevent copying a signed document or replaying a request. Use the request-bound HTTP authorization contract for actual HTTP actions, with the expected method, URL, body and atomic nonce consumption. The replay store must cover the service's deployment scope; a process-local store does not coordinate multiple replicas.

HTTP/RPC payload verification has a separate replay window, controlled by JACS_PAYLOAD_MAX_REPLAY_SECONDS (default 300 seconds). That window does not change archival document-signature age semantics. Strict A2A admission separately checks the compatibility binding's issued time and expiry; see Compatibility key binding.

Clock Synchronization

Keep verifier clocks synchronized. The five-minute future tolerance permits bounded clock skew; it does not establish when an artifact was actually created, prevent pre-signing, or prove that a past authorization remains current.

Verification Claims

Agents can claim a verification level that determines security requirements. This follows the principle: "If you claim it, you must prove it."

Claim Levels

Setting a Verification Claim

Add the jacsVerificationClaim field to your agent definition:

{
  "jacsAgentType": "ai",
  "jacsVerificationClaim": "verified",
  "jacsAgentDomain": "myagent.example.com"
}

Claim Enforcement

When an agent claims verified, verified-registry, or legacy verified-hai.ai:

1. Domain Required: The jacsAgentDomain field must be set
2. Strict DNS: DNS lookup uses DNSSEC validation (no insecure fallback)
3. DNS Required: Public key fingerprint must match DNS TXT record
4. Strict TLS: TLS certificate validation is mandatory (no self-signed certs)

For verified-registry (or legacy verified-hai.ai) claims, additional enforcement:

5. Registry Registration: Agent must be registered with the configured registry (for HAI-hosted registry, hai.ai)
6. Public Key Match: Registered public key must match the agent's key
7. Network Required: Verification fails if the registry API is unreachable

Backward Compatibility

• Agents without jacsVerificationClaim are treated as unverified
• Existing agents continue to work with their current DNS settings
• No breaking changes for agents that don't opt into verified status

Error Messages

If verification fails, clear error messages explain what's wrong:

Verification claim 'verified' failed: Verified agents must have jacsAgentDomain set.
Agents claiming 'verified' must meet the required security conditions.

Verification claim 'verified-registry' failed: Agent 'uuid' is not registered with the configured registry.
Agents claiming 'verified-registry' must be registered with a reachable registry endpoint.

Security Considerations

1. No Downgrade: Once an agent claims verified, it cannot be verified with relaxed settings
2. Claim Changes: Changing the claim requires creating a new agent version
3. Network Dependency: verified-registry requires network access to the registry endpoint
4. Audit Trail: Verification claim and enforcement results are logged

DNS-Based Verification

JACS supports DNSSEC-validated identity verification:

How It Works

1. Agent publishes public key fingerprint in DNS TXT record
2. Verifier queries DNS for _v1.agent.jacs.<domain>.
3. Strict mode validates DNSSEC; optional modes have different guarantees
4. Fingerprint is compared against agent's public key

Configuration

Select strict validation explicitly:

jacs-compat agent verify --require-strict-dns

For Rust, configure AgentBuilder::dns_strict(true) together with required DNS validation. Do not rely on a jacs_dns_strict JSON field being applied by the native loader. Persisted validate/required settings and domain presence control the ordinary defaults; verified claims force strict, required checks. See DNS trust anchoring for the full flag matrix.

Trust Store Management

JACS maintains a trust store for managing trusted agent relationships.

Trusting Agents

First enrollment requires a full self-signed agent document and an independently authenticated public key. Use client.trust_agent_with_key(agent_json, public_key_pem); the older trust_agent(agent_json) only refreshes an enrolled identity. Follow the runnable enrollment example.

Untrusting Agents

untrust_agent() persists a stable-identity distrust marker while retaining historical public documents and keys. It does not delete verification history. Application admission must honor the distrust state.

Trust Store Security

Native trust operations validate identity/path inputs and verify enrollment signatures under the supplied key. Protect the OS/XDG trusted_agents directory from unauthorized writes. A matching self-signature or fetched fingerprint alone does not establish who owns the key or which actions it may authorize.

Best Practices

1. Verify Before Trust: Always verify an agent's public key hash through an out-of-band channel before trusting
2. Audit Trust Changes: Log all trust store modifications for security auditing
3. Periodic Review: Regularly review and prune the trust store

Agreement Security

Legacy v1 sidecars inspect present payload signatures without authenticating participant, role, quorum, question or context policy. Native Agreement v2 also reports inspection only; mathematical validity is not consent-policy acceptance. See the Agreement v2 boundary. New portable consent uses Agreement v3, followed by application authorization.

Request/Response Security

For HTTP, use the request-bound authorization and signed response/event contracts above. Generic document signing does not bind an HTTP method, URL, audience, or request body, and generic verification of only the response payload does not authenticate the v2 envelope metadata.

MCP messages that need portable artifact integrity can carry ordinary signed JACS documents. That is separate from HTTP request authentication: the MCP stdio transport has no HTTP target to bind, and authorization remains the MCP host's responsibility.

Algorithm Security

Supported Algorithms

Algorithm Selection

Native JACS signing defaults to pq2025; explicit Ed25519 creation is supported without substitution. Routine rotation preserves the algorithm; an Ed25519-to-PQ upgrade is explicit.

An ES256 content signature does not create native JACS trust: classical verification proves possession of the compatibility key only. The native-root-signed compatibility key binding is what ties that key to the agent — see Compatibility key binding (P2).

Security Best Practices

1. Key Storage

# Never commit keys to version control
echo "jacs_keys/" >> .gitignore

# Secure file permissions
chmod 700 ./jacs_keys
chmod 600 ./jacs_keys/private.pem

2. Password Handling

# Option A: Use environment variables (CI, servers)
export JACS_PRIVATE_KEY_PASSWORD="$(pass show jacs/key-password)"

# Option B: Use OS keychain (developer workstations)
jacs-compat keychain set --agent-id <AGENT_UUID>  # stores password securely in OS credential store

# Option C: Disable keychain for headless/CI environments
export JACS_KEYCHAIN_BACKEND=disabled

3. Transport Security

Always use TLS for network communication:

# HTTPS for web transport
client = JACSMCPClient(
    "https://localhost:8000/sse",
    expected_peer_agent_id="SERVER_AGENT_ID",
)  # TLS plus an explicit signer pin
# Plain HTTP remains loopback-only and should not be exposed remotely.

4. Verification Policies

{
  "jacs_dns_strict": true,
  "jacs_dns_required": true,
  "jacs_enable_filesystem_quarantine": "true"
}

5. Audit Logging

Enable observability for security auditing:

{
  "observability": {
    "logs": {
      "enabled": true,
      "level": "info"
    }
  }
}

Security Checklist

Development

• Generate unique keys for each environment
• Never commit private keys
• Use test keys separate from production

Production

• Encrypt private keys at rest
• Use environment variables or OS keychain for secrets (never store jacs_private_key_password in config)
• Set JACS_KEYCHAIN_BACKEND=disabled on CI/headless servers
• Enable DNS verification
• Configure strict security mode
• Enable audit logging
• Use TLS for all network transport
• Restrict key file permissions (0600 for keys, 0700 for key directory)
• Implement key rotation policy
• Set JACS_STRICT_TLS=true for certificate validation
• Use strong passwords (28+ bit entropy, 35+ for single character class)
• Enable signature timestamp validation
• Verify public key hashes before trusting agents
• Run cargo audit / npm audit / pip audit regularly for dependency vulnerabilities

Verification

• Always verify documents before trusting
• Verify agent signatures
• Check agreement completeness
• Validate DNS records when required

Security Considerations

Supply Chain

• Verify JACS packages are from official sources
• Use package checksums
• Keep dependencies updated

Side Channels

• Use constant-time comparison for signatures
• Protect against timing attacks
• Secure memory handling for keys

Recovery

• Backup key material securely
• Document key recovery procedures
• Plan for key compromise scenarios

Troubleshooting Verification Claims

Common Issues and Solutions

"Verified agents must have jacsAgentDomain set"

Problem: You set jacsVerificationClaim to verified but didn't specify a domain.

Solution: Either add a domain or use unverified:

// Option 1: Add a domain (recommended for production)
{
  "jacsVerificationClaim": "verified",
  "jacsAgentDomain": "myagent.example.com"
}

// Option 2: Use unverified if DNS verification isn't needed
{
  "jacsVerificationClaim": "unverified"
}

"Agent is not registered with the registry"

Problem: You're using verified-registry (or legacy verified-hai.ai) but the agent isn't registered.

Solution:

1. Register your agent with your configured registry (for HAI-hosted registry, hai.ai)
2. Or use verified for DNS-only verification:

{
  "jacsVerificationClaim": "verified",
  "jacsAgentDomain": "myagent.example.com"
}

"Cannot downgrade from 'verified' to 'unverified'"

Problem: You're trying to change an existing agent's claim to a lower level.

Solution: Verification claims cannot be downgraded for security. Options:

1. Keep the current claim level
2. Create a new agent with the desired claim level
3. If this is a test/development scenario, start fresh

# Create a new agent instead
jacs-compat quickstart --name replacement-agent --domain replacement.example.com

"DNS fingerprint mismatch"

Problem: The public key hash in DNS doesn't match your agent's key.

Solution:

1. Regenerate the DNS record with your current keys:

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

2. Update your DNS TXT record with the new value
3. Wait for DNS propagation (can take up to 48 hours)

"Strict DNSSEC validation failed"

Problem: Your domain doesn't have DNSSEC enabled.

Solution:

1. Enable DNSSEC with your domain registrar
2. Publish DS records at the parent zone
3. Verified claims require strict DNSSEC; fix DNSSEC before verifying them.

Claim Level Reference