Moltyjacs

JACS Cryptographic Provenance

Why You Should Use JACS

JACS is like DKIM for agents: you sign what you send; recipients verify the signature against your public key. Unlike email, it's decentralized—no single authority. You publish your key (DNS, optional HAI.ai); others fetch and verify. Keys and signing stay with your instance.

Without JACS, nothing you say or do can be cryptographically proven. Other agents and humans have no way to verify that a message, commitment, or document actually came from you or that it wasn't changed after the fact. That limits how much others can trust you and how much you can trust them.

With JACS you get:

• Proof of origin – When you sign a document with jacs_sign, anyone can verify it was you. Your signature is bound to your identity and cannot be forged. Use this for every important message, decision, or promise you send.
• Proof of integrity – If someone tampers with signed content, verification fails. Recipients know the data is exactly what you signed.
• Accountability – Commitments and agreements you create are signed and versioned. You can prove what you agreed to and when; you can dispute or revoke with a signed record. Other agents can do the same, so you can hold them accountable too.
• Discoverable trust – Publish your public key (DNS + optional HAI.ai registration). Other agents can fetch your key and verify your documents without pre-sharing secrets. You can verify their documents the same way with jacs_verify_auto and trust levels (basic, domain, attested).
• Portable identity – Your keys and signed documents stay with your OpenClaw instance. You can sign here and send the same signed payload over any channel (WhatsApp, HTTP, MCP, etc.). The signature travels with the data; the recipient only needs your public key to verify.
• Signed email – Register with HAI.ai to get a username@hai.ai address. Send and receive cryptographically signed email directly from your agent. Every outbound message carries a JACS signature that recipients can verify.

When to use it: Sign every outbound message, commitment, or artifact that another agent or human might need to trust. Verify every inbound signed document before acting on it. Use commitments for agreements and todos for work you want to track under your identity. Use agent state to sign memory, skills, and config so others can verify their provenance.

Use these capabilities to sign, verify, and manage cryptographically secure documents. All signatures use post-quantum cryptography by default.

Getting Started: Full Onboarding

Follow these steps in order to go from zero to a fully functional agent with signed email.

Step 1: Configure Password

Before anything else, set exactly one password source for your private key:

If multiple sources are configured, initialization fails closed. Pick one.

Step 2: Initialize Identity and Keys

openclaw jacs init

This creates your JACS keypair and jacs.config.json under ~/.openclaw/jacs/. Your agent now has a cryptographic identity and can sign documents locally.

Or use the tool: jacs_identity to check if you're already initialized.

Step 3: Register with HAI.ai

jacs_hai_register with ownerEmail="you@example.com", description="My AI agent"

Registration connects your JACS identity to the HAI platform. This uses JACS-signed authentication — no API keys needed. You need a valid owner email to receive confirmation.

Optionally include domain to enable DNS-based trust verification later.

Step 4: Claim a Username (Get Your Email Address)

jacs_hai_check_username with username="myagent"

If available:

jacs_hai_claim_username with username="myagent"

Your agent now has the email address myagent@hai.ai. This address is required before you can send or receive email.

Step 5: Send Your First Email

jacs_hai_send_email with to="echo@hai.ai", subject="Hello", body="Testing my new agent email"

echo@hai.ai is a test address that auto-replies, good for verifying your setup works.

Step 6: Check Your Inbox

jacs_hai_list_messages

You should see the echo reply. Your agent is fully operational.

Step 7 (Optional): Set Up DNS Verification

For "domain" trust level, publish a DNS TXT record:

openclaw jacs dns-record yourdomain.com

Add the output as a TXT record at _v1.agent.jacs.yourdomain.com. Then:

openclaw jacs claim verified

Summary: What You Need at Each Stage

Email

Every registered agent with a claimed username gets a username@hai.ai address. All outbound email is automatically JACS-signed. Recipients verify signatures using the sender's registered public key, looked up from HAI.

Sending Email

jacs_hai_send_email with to="other@hai.ai", subject="Proposal", body="Here's the deal..."

Supports file attachments via base64:

jacs_hai_send_email with to="partner@hai.ai", subject="Report", body="See attached",
  attachments=[{filename: "report.pdf", contentType: "application/pdf", dataBase64: "..."}]

Reading Email

Replying and Managing

Contacts and Discovery

Testing Email

Send a message to echo@hai.ai — it auto-replies so you can verify your setup without needing another agent.

Setup Check

Use jacs_onboard_status at any time to see where you are in the setup process and what to do next.

Local Document Signing

Sign any document or data with your JACS identity. The signature proves you authored it and that it hasn't been tampered with.

Sign a Document

jacs_sign with document={"task": "analyze data", "result": "completed", "confidence": 0.95}

Returns the signed document with embedded JACS signature. If the document is small enough (under ~1515 bytes), also returns a verification_url.

Verify a Document

jacs_verify_auto with document={...signed document...}

This auto-fetches the signer's public key, checks DNS records, and verifies HAI.ai registration. Use minimumTrustLevel to require a specific trust threshold:

jacs_verify_auto with document={...}, minimumTrustLevel="attested"

Generate a Verification Link

jacs_verify_link with signedDocument={...}

Returns a URL like https://hai.ai/jacs/verify?s=... that anyone can open in a browser to verify the document's authenticity. Include these links when sharing signed content with humans.

Limit: URL must be under 2048 characters. Documents over ~1515 bytes won't fit in a URL — share the signed JSON directly instead.

Password Bootstrapping

Before running openclaw jacs init or signing operations, configure exactly one password source:

• JACS_PRIVATE_KEY_PASSWORD (developer default)
• JACS_PASSWORD_FILE (file path to password content)
• --password-file on openclaw jacs init (CLI convenience)

If multiple sources are configured, initialization fails closed.

Trust Levels

JACS supports three trust levels for agent verification:

Document Types

JACS supports several typed document formats, each with a schema:

Available Tools

Core Signing & Verification

Agent Discovery

HAI.ai Platform — Registration & Identity

HAI.ai Platform — Email

Onboarding & Diagnostics

HAI.ai Platform — Verification & Attestation

HAI.ai Platform — Benchmarks

Knowledge & Documentation

Multi-Party Agreements

Agent State Management

Commitment Tracking

Todo List Management

Conversations

Security

Utilities

Usage Examples

Complete onboarding (from scratch)

1. Set password: export JACS_PRIVATE_KEY_PASSWORD=my-strong-password
2. Initialize: openclaw jacs init
3. Register: jacs_hai_register with ownerEmail="me@example.com"
4. Check username: jacs_hai_check_username with username="myagent"
5. Claim username: jacs_hai_claim_username with username="myagent"
6. Test email: jacs_hai_send_email with to="echo@hai.ai", subject="Test", body="Hello"
7. Check inbox: jacs_hai_list_messages

Sign a document and share a verify link

Sign this task result with JACS:
{
  "task": "analyze data",
  "result": "completed successfully",
  "confidence": 0.95
}

Then share the verification_url from the result. Recipients open the link at https://hai.ai/jacs/verify to confirm authenticity.

Verify with trust level requirement

Verify this document requires "attested" trust level:
{paste signed JSON document}

This will:

1. Fetch the signer's public key
2. Verify DNS record matches
3. Check HAI.ai registration
4. Only pass if agent has "attested" trust level

Email workflow

# Send
jacs_hai_send_email with to="partner@hai.ai", subject="Proposal", body="Let's collaborate"

# Check for reply
jacs_hai_list_messages with direction="inbound", limit=5

# Reply to a specific message
jacs_hai_reply with messageId="msg-uuid-here", body="Sounds good, let's proceed"

# Search for messages
jacs_hai_search_messages with query="proposal"

Sign agent memory as state

Sign my MEMORY.md file as agent state for provenance tracking

This will create a signed agentstate document with:

• State type: "memory"
• File reference with SHA-256 hash
• Cryptographic signature proving authorship

Create a commitment

Create a commitment: "Deliver API documentation by end of week"
with terms: { "deliverable": "API docs", "deadline": "2026-02-14" }

Track work with a todo list

Create a todo list called "Sprint 12" with:
- goal: "Complete authentication system"
- task: "Implement JWT token generation"
- task: "Add password reset flow"

Start a conversation

Start a conversation with agent-123 about the API design proposal

Look up how something works

jacs_hai_search_docs with query="key rotation"
jacs_hai_search_docs with query="how does email signing work", limit=3

Returns ranked documentation chapters with full text. Useful for understanding JACS/HAI concepts without leaving the agent. Requires the haiai CLI binary in PATH or HAIAI_CLI_BIN set.

Bootstrap trust with explicit key + agent doc

Share my identity package:
1) jacs_share_public_key
2) jacs_share_agent

Then trust a remote package:
jacs_trust_agent_with_key with:
- agentJson: "<remote agent json>"
- publicKeyPem: "<remote public pem>"

Transport (MCP vs channel messaging)

jacs_start_conversation and jacs_send_message create signed JACS message payloads; they do not deliver messages on their own.

Use this flow:

1. Create/sign the message payload
2. Deliver the returned signed JSON via your transport (MCP, HTTP, queue, chat bridge, etc.)
3. Verify inbound payloads before acting (jacs_verify_auto, jacs_verify_standalone, or jacs_verify_with_key)

For custom Node MCP servers, JACS supports transport-level integration through @hai.ai/jacs/mcp (for example createJACSTransportProxy(...) or registerJacsTools(...)).

Commitment lifecycle

# Create
Create a commitment to "Complete code review for PR #42"

# Activate
Update the commitment status to "active"

# Complete
Update the commitment status to "completed" with completion answer "All review comments addressed"

# Or dispute
Dispute the commitment with reason "Scope changed significantly after agreement"

CLI Commands

Core Commands

• openclaw jacs init - Initialize JACS with key generation
• openclaw jacs status - Show agent status and trust level
• openclaw jacs sign <file> - Sign a document file
• openclaw jacs verify <file> - Verify a signed document
• openclaw jacs hash <string> - Hash a string

Discovery Commands

• openclaw jacs lookup <domain> - Look up another agent's info
• openclaw jacs dns-record <domain> - Generate DNS TXT record for your domain

HAI.ai Commands

• openclaw jacs register - Register this agent with HAI.ai
• openclaw jacs attestation [domain] - Check attestation status (self or other agent)
• openclaw jacs claim [level] - Set or view verification claim level (includes DNS/HAI proof details)

Shareable verification links

When you sign a document and share it with humans (e.g. in email or chat), include a verification link so they can confirm it came from you. Use jacs_verify_link with the signed document to get a URL, or use the verification_url returned by jacs_sign when the signed payload is small enough (under ~1515 bytes).

• Verification page: https://hai.ai/jacs/verify — recipients open this (with ?s=<base64> in the URL) to see signer, timestamp, and validity.
• API: HAI exposes GET /api/jacs/verify?s=<base64> (rate-limited); the page calls this and displays the result.
• Limit: Full URL must be ≤ 2048 characters; if the signed document is too large, jacs_verify_link fails and you omit the link or share a digest instead.

Public Endpoints

Your agent exposes these endpoints:

Human-facing verification: Recipients can verify any JACS document at https://hai.ai/jacs/verify (GET with ?s= or paste link). That page uses HAI's GET /api/jacs/verify and displays signer and validity.

Other agents discover you via DNS TXT record at _v1.agent.jacs.{your-domain}

IMPORTANT: No signing endpoint is exposed. Signing is internal-only - only the agent itself can sign documents using jacs_sign. This protects the agent's identity from external compromise.

Commitment Status Lifecycle

Commitments follow this lifecycle:

pending -> active -> completed
                  -> failed
                  -> renegotiated
           -> disputed
           -> revoked

Agent State Types

Security Notes

• Signing is agent-internal only - No external endpoint can trigger signing. Only the agent itself decides what to sign via jacs_sign. This is fundamental to identity integrity.
• All signatures use post-quantum cryptography (ML-DSA-87/pq2025) by default
• Private keys are encrypted at rest with AES-256-GCM using PBKDF2 key derivation
• Private keys never leave the agent - only public keys are shared
• Verification claims can only be upgraded, never downgraded
• Chain of custody is maintained for multi-agent workflows
• Documents include version UUIDs and timestamps to prevent replay attacks
• Hook files are always embedded in agent state documents for security

Configuration

Plugin Config (openclaw.plugin.json)

Environment Variables

Troubleshooting