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