@hai.ai/jacs 0.6.0 → 0.8.0

package/express.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * JACS Express Middleware
+ *
+ * Factory-based middleware for Express v4/v5 that verifies incoming
+ * JACS-signed request bodies and optionally auto-signs JSON responses.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { JacsClient } from './client';
+ * import { jacsMiddleware } from './express';
+ *
+ * const client = await JacsClient.quickstart();
+ * 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' });
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jacsMiddleware = jacsMiddleware;
+// =============================================================================
+// Internal helpers
+// =============================================================================
+/** Methods that carry a request body. */
+const BODY_METHODS = new Set(['POST', 'PUT', 'PATCH']);
+async function resolveClient(options) {
+    if (options.client) {
+        return options.client;
+    }
+    // Lazy-import to avoid hard dependency on client.ts at module level
+    const { JacsClient: ClientCtor } = await import('./client.js');
+    if (options.configPath) {
+        const client = new ClientCtor();
+        await client.load(options.configPath);
+        return client;
+    }
+    return ClientCtor.quickstart();
+}
+// =============================================================================
+// Middleware factory
+// =============================================================================
+/**
+ * Create JACS Express middleware.
+ *
+ * The returned middleware attaches `req.jacsClient` on every request.
+ * When `verify` is true (default), POST/PUT/PATCH bodies are verified as
+ * JACS-signed documents and the extracted payload is set on `req.jacsPayload`.
+ * When `sign` is true, `res.json()` is intercepted to auto-sign the response.
+ */
+function jacsMiddleware(options = {}) {
+    const shouldVerify = options.verify !== false;
+    const shouldSign = options.sign === true;
+    const isOptional = options.optional === true;
+    // Client is resolved once (lazy, on first request) then cached.
+    let clientPromise = null;
+    function getClient() {
+        if (!clientPromise) {
+            clientPromise = resolveClient(options);
+        }
+        return clientPromise;
+    }
+    // Pre-resolve immediately if a client is already provided (avoids first-request latency).
+    if (options.client) {
+        clientPromise = Promise.resolve(options.client);
+    }
+    return async function jacsExpressMiddleware(req, res, next) {
+        let client;
+        try {
+            client = await getClient();
+        }
+        catch (err) {
+            res.status(500).json({ error: 'JACS initialization failed' });
+            return;
+        }
+        // Always expose the client on the request for manual use in route handlers.
+        req.jacsClient = client;
+        // ----- Verify incoming body -----
+        if (shouldVerify && BODY_METHODS.has(req.method)) {
+            const rawBody = typeof req.body === 'string' ? req.body : null;
+            if (rawBody) {
+                try {
+                    const result = await client.verify(rawBody);
+                    if (result.valid) {
+                        req.jacsPayload = result.data;
+                    }
+                    else if (!isOptional) {
+                        res.status(401).json({ error: 'JACS verification failed', details: result.errors });
+                        return;
+                    }
+                    // When optional and invalid, just continue without jacsPayload.
+                }
+                catch (err) {
+                    if (!isOptional) {
+                        res.status(401).json({ error: 'JACS verification failed', details: [String(err)] });
+                        return;
+                    }
+                }
+            }
+            else if (!isOptional && req.body !== undefined) {
+                // Body exists but is not a string — cannot verify.
+                // Only reject if body is present; missing body on POST may be handled by route.
+            }
+        }
+        // ----- Auto-sign responses -----
+        if (shouldSign) {
+            const originalJson = res.json.bind(res);
+            res.json = function jacsSignedJson(body) {
+                // Fire-and-forget async signing, then send via original json.
+                client
+                    .signMessage(body)
+                    .then((signed) => {
+                    originalJson(signed.raw);
+                })
+                    .catch(() => {
+                    // Signing failed — send unsigned to avoid hanging response.
+                    originalJson(body);
+                });
+                return res;
+            };
+        }
+        next();
+    };
+}
+//# sourceMappingURL=express.js.map

package/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["express.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;AAyFH,wCAmFC;AAvHD,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF,yCAAyC;AACzC,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAEvD,KAAK,UAAU,aAAa,CAAC,OAA8B;IACzD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,OAAO,CAAC,MAAM,CAAC;IACxB,CAAC;IAED,oEAAoE;IACpE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IAE/D,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAChC,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACtC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,UAAU,CAAC,UAAU,EAAE,CAAC;AACjC,CAAC;AAED,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,UAAiC,EAAE;IAChE,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC;IAC9C,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC;IACzC,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,KAAK,IAAI,CAAC;IAE7C,gEAAgE;IAChE,IAAI,aAAa,GAA+B,IAAI,CAAC;IAErD,SAAS,SAAS;QAChB,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,aAAa,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACzC,CAAC;QACD,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,0FAA0F;IAC1F,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,KAAK,UAAU,qBAAqB,CACzC,GAAgB,EAChB,GAAoB,EACpB,IAAyB;QAEzB,IAAI,MAAkB,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,4BAA4B,EAAE,CAAC,CAAC;YAC9D,OAAO;QACT,CAAC;QAED,4EAA4E;QAC5E,GAAG,CAAC,UAAU,GAAG,MAAM,CAAC;QAExB,mCAAmC;QACnC,IAAI,YAAY,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACjD,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YAE/D,IAAI,OAAO,EAAE,CAAC;gBACZ,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;oBAC5C,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;wBACjB,GAAG,CAAC,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC;oBAChC,CAAC;yBAAM,IAAI,CAAC,UAAU,EAAE,CAAC;wBACvB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,0BAA0B,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;wBACpF,OAAO;oBACT,CAAC;oBACD,gEAAgE;gBAClE,CAAC;gBAAC,OAAO,GAAQ,EAAE,CAAC;oBAClB,IAAI,CAAC,UAAU,EAAE,CAAC;wBAChB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,0BAA0B,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;wBACpF,OAAO;oBACT,CAAC;gBACH,CAAC;YACH,CAAC;iBAAM,IAAI,CAAC,UAAU,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACjD,mDAAmD;gBACnD,gFAAgF;YAClF,CAAC;QACH,CAAC;QAED,kCAAkC;QAClC,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,YAAY,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAExC,GAAG,CAAC,IAAI,GAAG,SAAS,cAAc,CAAC,IAAS;gBAC1C,8DAA8D;gBAC9D,MAAM;qBACH,WAAW,CAAC,IAAI,CAAC;qBACjB,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;oBACf,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC3B,CAAC,CAAC;qBACD,KAAK,CAAC,GAAG,EAAE;oBACV,4DAA4D;oBAC5D,YAAY,CAAC,IAAI,CAAC,CAAC;gBACrB,CAAC,CAAC,CAAC;gBACL,OAAO,GAAG,CAAC;YACb,CAAC,CAAC;QACJ,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/index.d.ts

@@ -3,12 +3,14 @@
 
 /* auto-generated by NAPI-RS */
 
-/** Hash a string using SHA-256. */
+/** Hash a string using SHA-256. Sync-only (pure CPU, fast). */
 export declare function hashString(data: string): string
-/** Create a JACS configuration object. */
+/** Create a JACS configuration object. Sync-only (minimal CPU). */
 export declare function createConfig(jacsUseSecurity?: string | undefined | null, jacsDataDirectory?: string | undefined | null, jacsKeyDirectory?: string | undefined | null, jacsAgentPrivateKeyFilename?: string | undefined | null, jacsAgentPublicKeyFilename?: string | undefined | null, jacsAgentKeyAlgorithm?: string | undefined | null, jacsPrivateKeyPassword?: string | undefined | null, jacsAgentIdAndVersion?: string | undefined | null, jacsDefaultStorage?: string | undefined | null): string
-/** Create a JACS agent programmatically (non-interactive). */
-export declare function createAgent(name: string, password: string, algorithm?: string | undefined | null, dataDirectory?: string | undefined | null, keyDirectory?: string | undefined | null, configPath?: string | undefined | null, agentType?: string | undefined | null, description?: string | undefined | null, domain?: string | undefined | null, defaultStorage?: string | undefined | null): string
+/** Create a JACS agent programmatically (sync, blocks event loop). */
+export declare function createAgentSync(name: string, password: string, algorithm?: string | undefined | null, dataDirectory?: string | undefined | null, keyDirectory?: string | undefined | null, configPath?: string | undefined | null, agentType?: string | undefined | null, description?: string | undefined | null, domain?: string | undefined | null, defaultStorage?: string | undefined | null): string
+/** Create a JACS agent programmatically (async, returns Promise). */
+export declare function createAgent(name: string, password: string, algorithm?: string | undefined | null, dataDirectory?: string | undefined | null, keyDirectory?: string | undefined | null, configPath?: string | undefined | null, agentType?: string | undefined | null, description?: string | undefined | null, domain?: string | undefined | null, defaultStorage?: string | undefined | null): Promise<string>
 /** Add an agent to the local trust store. */
 export declare function trustAgent(agentJson: string): string
 /** List all trusted agent IDs. */
@@ -19,28 +21,31 @@ export declare function untrustAgent(agentId: string): void
 export declare function isTrusted(agentId: string): boolean
 /** Get a trusted agent's JSON document. */
 export declare function getTrustedAgent(agentId: string): string
-/**
- * Run a read-only security audit and health checks.
- * Returns the audit result as a JSON string (risks, health_checks, summary).
- */
-export declare function audit(configPath?: string | undefined | null, recentN?: number | undefined | null): string
+/** Run a security audit (sync, blocks event loop). */
+export declare function auditSync(configPath?: string | undefined | null, recentN?: number | undefined | null): string
+/** Run a security audit (async, returns Promise). */
+export declare function audit(configPath?: string | undefined | null, recentN?: number | undefined | null): Promise<string>
 /** @deprecated Use `new JacsAgent()` and `agent.load()` instead. */
-export declare function load(configPath: string): string
+export declare function legacyLoad(configPath: string): string
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function signAgent(agentString: string, publicKey: Buffer, publicKeyEncType: string): string
+export declare function legacySignAgent(agentString: string, publicKey: Buffer, publicKeyEncType: string): string
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function verifyString(data: string, signatureBase64: string, publicKey: Buffer, publicKeyEncType: string): boolean
+export declare function legacyVerifyString(data: string, signatureBase64: string, publicKey: Buffer, publicKeyEncType: string): boolean
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function signString(data: string): string
+export declare function legacySignString(data: string): string
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function verifyAgent(agentfile?: string | undefined | null): boolean
+export declare function legacyVerifyAgent(agentfile?: string | undefined | null): boolean
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function updateAgent(newAgentString: string): string
-/** Result of verify_document_standalone. Exposed to JS as { valid, signerId }. */
+export declare function legacyUpdateAgent(newAgentString: string): string
+/** Result of verify_document_standalone. Exposed to JS as { valid, signerId, timestamp, agentVersion }. */
 export interface VerifyStandaloneResult {
   valid: boolean
   /** Signer agent ID; exposed to JS as signerId (camelCase). */
   signerId: string
+  /** Signing timestamp from jacsSignature.date. */
+  timestamp: string
+  /** Signer agent version from jacsSignature.agentVersion. */
+  agentVersion: string
 }
 /**
  * Verify a signed JACS document without loading an agent.
@@ -48,31 +53,26 @@ export interface VerifyStandaloneResult {
  */
 export declare function verifyDocumentStandalone(signedDocument: string, keyResolution?: string | undefined | null, dataDirectory?: string | undefined | null, keyDirectory?: string | undefined | null): VerifyStandaloneResult
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function verifyDocument(documentString: string): boolean
+export declare function legacyVerifyDocument(documentString: string): boolean
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function updateDocument(documentKey: string, newDocumentString: string, attachments?: Array<string> | undefined | null, embed?: boolean | undefined | null): string
+export declare function legacyUpdateDocument(documentKey: string, newDocumentString: string, attachments?: Array<string> | undefined | null, embed?: boolean | undefined | null): string
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function verifySignature(documentString: string, signatureField?: string | undefined | null): boolean
+export declare function legacyVerifySignature(documentString: string, signatureField?: string | undefined | null): boolean
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function createAgreement(documentString: string, agentids: Array<string>, question?: string | undefined | null, context?: string | undefined | null, agreementFieldname?: string | undefined | null): string
+export declare function legacyCreateAgreement(documentString: string, agentids: Array<string>, question?: string | undefined | null, context?: string | undefined | null, agreementFieldname?: string | undefined | null): string
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function signAgreement(documentString: string, agreementFieldname?: string | undefined | null): string
+export declare function legacySignAgreement(documentString: string, agreementFieldname?: string | undefined | null): string
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function createDocument(documentString: string, customSchema?: string | undefined | null, outputfilename?: string | undefined | null, noSave?: boolean | undefined | null, attachments?: string | undefined | null, embed?: boolean | undefined | null): string
+export declare function legacyCreateDocument(documentString: string, customSchema?: string | undefined | null, outputfilename?: string | undefined | null, noSave?: boolean | undefined | null, attachments?: string | undefined | null, embed?: boolean | undefined | null): string
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function checkAgreement(documentString: string, agreementFieldname?: string | undefined | null): string
+export declare function legacyCheckAgreement(documentString: string, agreementFieldname?: string | undefined | null): string
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function signRequest(params: any): string
+export declare function legacySignRequest(params: any): string
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function verifyResponse(documentString: string): object
+export declare function legacyVerifyResponse(documentString: string): object
 /** @deprecated Use `new JacsAgent()` and instance methods instead. */
-export declare function verifyResponseWithAgentId(documentString: string): object
-/**
- * Information about a public key fetched from HAI key service.
- *
- * This struct contains the public key data and metadata returned by
- * the HAI key distribution service.
- */
+export declare function legacyVerifyResponseWithAgentId(documentString: string): object
+/** Information about a public key fetched from HAI key service. */
 export interface RemotePublicKeyInfo {
   /** The raw public key bytes (DER encoded). */
   publicKey: Buffer
@@ -85,44 +85,9 @@ export interface RemotePublicKeyInfo {
   /** The version of the key. */
   version: string
 }
-/**
- * Fetch a public key from HAI's key distribution service.
- *
- * This function retrieves the public key for a specific agent and version
- * from the HAI key distribution service. It is used to obtain trusted public
- * keys for verifying agent signatures without requiring local key storage.
- *
- * # Arguments
- *
- * * `agent_id` - The unique identifier of the agent whose key to fetch.
- * * `version` - The version of the agent's key to fetch. Use "latest" for
- *   the most recent version. If not provided, defaults to "latest".
- *
- * # Returns
- *
- * Returns a `RemotePublicKeyInfo` object containing the public key, algorithm, and hash.
- *
- * # Environment Variables
- *
- * * `HAI_KEYS_BASE_URL` - Base URL for the key service. Defaults to `https://keys.hai.ai`.
- *
- * # Example
- *
- * ```javascript
- * const { fetchRemoteKey } = require('@hai.ai/jacs');
- *
- * const keyInfo = fetchRemoteKey('550e8400-e29b-41d4-a716-446655440000', 'latest');
- * console.log('Algorithm:', keyInfo.algorithm);
- * console.log('Hash:', keyInfo.publicKeyHash);
- * ```
- */
+/** Fetch a public key from HAI's key distribution service. */
 export declare function fetchRemoteKey(agentId: string, version?: string | undefined | null): RemotePublicKeyInfo
-/**
- * Build a verification URL for a signed JACS document.
- *
- * Encodes `document` as URL-safe base64 (no padding) and returns a full URL
- * like `https://hai.ai/jacs/verify?s=...`. Throws if the URL would exceed 2048 chars.
- */
+/** Build a verification URL for a signed JACS document. */
 export declare function generateVerifyLink(document: string, baseUrl: string): string
 /**
  * JacsAgent is a handle to a JACS agent instance.
@@ -135,44 +100,100 @@ export declare class JacsAgent {
    * Call `load()` to initialize it with a configuration.
    */
   constructor()
+  /** Load an agent from a configuration file (sync, blocks event loop). */
+  loadSync(configPath: string): string
+  /** Create an ephemeral in-memory agent (sync, blocks event loop). */
+  ephemeralSync(algorithm?: string | undefined | null): string
+  /** Sign an external agent's document (sync, blocks event loop). */
+  signAgentSync(agentString: string, publicKey: Buffer, publicKeyEncType: string): string
+  /** Verify a signature on arbitrary string data (sync, blocks event loop). */
+  verifyStringSync(data: string, signatureBase64: string, publicKey: Buffer, publicKeyEncType: string): boolean
+  /** Sign arbitrary string data (sync, blocks event loop). */
+  signStringSync(data: string): string
+  /** Verify this agent's signature and hash (sync, blocks event loop). */
+  verifyAgentSync(agentfile?: string | undefined | null): boolean
+  /** Update the agent document (sync, blocks event loop). */
+  updateAgentSync(newAgentString: string): string
+  /** Verify a document's signature and hash (sync, blocks event loop). */
+  verifyDocumentSync(documentString: string): boolean
+  /** Update an existing document (sync, blocks event loop). */
+  updateDocumentSync(documentKey: string, newDocumentString: string, attachments?: Array<string> | undefined | null, embed?: boolean | undefined | null): string
+  /** Verify a document's signature with optional custom field (sync, blocks event loop). */
+  verifySignatureSync(documentString: string, signatureField?: string | undefined | null): boolean
+  /** Create an agreement on a document (sync, blocks event loop). */
+  createAgreementSync(documentString: string, agentids: Array<string>, question?: string | undefined | null, context?: string | undefined | null, agreementFieldname?: string | undefined | null): string
+  /** Create an agreement with extended options (sync, blocks event loop). */
+  createAgreementWithOptionsSync(documentString: string, agentids: Array<string>, question?: string | undefined | null, context?: string | undefined | null, agreementFieldname?: string | undefined | null, timeout?: string | undefined | null, quorum?: number | undefined | null, requiredAlgorithms?: Array<string> | undefined | null, minimumStrength?: string | undefined | null): string
+  /** Sign an agreement on a document (sync, blocks event loop). */
+  signAgreementSync(documentString: string, agreementFieldname?: string | undefined | null): string
+  /** Create a new JACS document (sync, blocks event loop). */
+  createDocumentSync(documentString: string, customSchema?: string | undefined | null, outputfilename?: string | undefined | null, noSave?: boolean | undefined | null, attachments?: string | undefined | null, embed?: boolean | undefined | null): string
+  /** Check an agreement on a document (sync, blocks event loop). */
+  checkAgreementSync(documentString: string, agreementFieldname?: string | undefined | null): string
+  /** Get setup instructions (sync, blocks event loop). */
+  getSetupInstructionsSync(domain: string, ttl?: number | undefined | null): string
+  /** Register with HAI.ai (sync, blocks event loop). */
+  registerWithHaiSync(apiKey?: string | undefined | null, haiUrl?: string | undefined | null, preview?: boolean | undefined | null): string
+  /**
+   * Returns diagnostic information as a JSON string.
+   * Lightweight — no async variant needed.
+   */
+  diagnostics(): string
+  /** Verify a document by ID (sync, blocks event loop). */
+  verifyDocumentByIdSync(documentId: string): boolean
+  /** Re-encrypt the agent's private key (sync, blocks event loop). */
+  reencryptKeySync(oldPassword: string, newPassword: string): void
+  /**
+   * Sign a request payload (wraps in a JACS document).
+   * Sync-only: uses V8 thread-local JsObject.
+   */
+  signRequest(params: any): string
+  /**
+   * Verify a response payload.
+   * Sync-only: returns V8 thread-local JsObject.
+   */
+  verifyResponse(documentString: string): object
+  /**
+   * Verify a response payload and return the agent ID.
+   * Sync-only: returns V8 thread-local JsObject.
+   */
+  verifyResponseWithAgentId(documentString: string): object
   /** Load an agent from a configuration file. */
-  load(configPath: string): string
-  /** Sign an external agent's document with this agent's registration signature. */
-  signAgent(agentString: string, publicKey: Buffer, publicKeyEncType: string): string
+  load(configPath: string): Promise<string>
+  /** Create an ephemeral in-memory agent. */
+  ephemeral(algorithm?: string | undefined | null): Promise<string>
+  /** Sign an external agent's document. */
+  signAgent(agentString: string, publicKey: Buffer, publicKeyEncType: string): Promise<string>
   /** Verify a signature on arbitrary string data. */
-  verifyString(data: string, signatureBase64: string, publicKey: Buffer, publicKeyEncType: string): boolean
+  verifyString(data: string, signatureBase64: string, publicKey: Buffer, publicKeyEncType: string): Promise<boolean>
   /** Sign arbitrary string data with this agent's private key. */
-  signString(data: string): string
+  signString(data: string): Promise<string>
   /** Verify this agent's signature and hash. */
-  verifyAgent(agentfile?: string | undefined | null): boolean
+  verifyAgent(agentfile?: string | undefined | null): Promise<boolean>
   /** Update the agent document with new data. */
-  updateAgent(newAgentString: string): string
+  updateAgent(newAgentString: string): Promise<string>
   /** Verify a document's signature and hash. */
-  verifyDocument(documentString: string): boolean
+  verifyDocument(documentString: string): Promise<boolean>
   /** Update an existing document. */
-  updateDocument(documentKey: string, newDocumentString: string, attachments?: Array<string> | undefined | null, embed?: boolean | undefined | null): string
+  updateDocument(documentKey: string, newDocumentString: string, attachments?: Array<string> | undefined | null, embed?: boolean | undefined | null): Promise<string>
   /** Verify a document's signature with an optional custom signature field. */
-  verifySignature(documentString: string, signatureField?: string | undefined | null): boolean
+  verifySignature(documentString: string, signatureField?: string | undefined | null): Promise<boolean>
   /** Create an agreement on a document. */
-  createAgreement(documentString: string, agentids: Array<string>, question?: string | undefined | null, context?: string | undefined | null, agreementFieldname?: string | undefined | null): string
+  createAgreement(documentString: string, agentids: Array<string>, question?: string | undefined | null, context?: string | undefined | null, agreementFieldname?: string | undefined | null): Promise<string>
+  /** Create an agreement with extended options. */
+  createAgreementWithOptions(documentString: string, agentids: Array<string>, question?: string | undefined | null, context?: string | undefined | null, agreementFieldname?: string | undefined | null, timeout?: string | undefined | null, quorum?: number | undefined | null, requiredAlgorithms?: Array<string> | undefined | null, minimumStrength?: string | undefined | null): Promise<string>
   /** Sign an agreement on a document. */
-  signAgreement(documentString: string, agreementFieldname?: string | undefined | null): string
+  signAgreement(documentString: string, agreementFieldname?: string | undefined | null): Promise<string>
   /** Create a new JACS document. */
-  createDocument(documentString: string, customSchema?: string | undefined | null, outputfilename?: string | undefined | null, noSave?: boolean | undefined | null, attachments?: string | undefined | null, embed?: boolean | undefined | null): string
+  createDocument(documentString: string, customSchema?: string | undefined | null, outputfilename?: string | undefined | null, noSave?: boolean | undefined | null, attachments?: string | undefined | null, embed?: boolean | undefined | null): Promise<string>
   /** Check an agreement on a document. */
-  checkAgreement(documentString: string, agreementFieldname?: string | undefined | null): string
-  /**
-   * Verify a document looked up by ID from storage.
-   *
-   * The document_id should be in "uuid:version" format.
-   */
-  verifyDocumentById(documentId: string): boolean
+  checkAgreement(documentString: string, agreementFieldname?: string | undefined | null): Promise<string>
+  /** Get setup instructions for DNS records, DNSSEC, and HAI registration. */
+  getSetupInstructions(domain: string, ttl?: number | undefined | null): Promise<string>
+  /** Register this agent with HAI.ai. */
+  registerWithHai(apiKey?: string | undefined | null, haiUrl?: string | undefined | null, preview?: boolean | undefined | null): Promise<string>
+  /** Verify a document looked up by ID from storage. */
+  verifyDocumentById(documentId: string): Promise<boolean>
   /** Re-encrypt the agent's private key with a new password. */
-  reencryptKey(oldPassword: string, newPassword: string): void
-  /** Sign a request payload (wraps in a JACS document). */
-  signRequest(params: any): string
-  /** Verify a response payload. */
-  verifyResponse(documentString: string): object
-  /** Verify a response payload and return the agent ID. */
-  verifyResponseWithAgentId(documentString: string): object
+  reencryptKey(oldPassword: string, newPassword: string): Promise<void>
 }

package/index.js

@@ -310,34 +310,36 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { JacsAgent, hashString, createConfig, createAgent, trustAgent, listTrustedAgents, untrustAgent, isTrusted, getTrustedAgent, audit, load, signAgent, verifyString, signString, verifyAgent, updateAgent, verifyDocumentStandalone, verifyDocument, updateDocument, verifySignature, createAgreement, signAgreement, createDocument, checkAgreement, signRequest, verifyResponse, verifyResponseWithAgentId, fetchRemoteKey, generateVerifyLink } = nativeBinding
+const { JacsAgent, hashString, createConfig, createAgentSync, createAgent, trustAgent, listTrustedAgents, untrustAgent, isTrusted, getTrustedAgent, auditSync, audit, legacyLoad, legacySignAgent, legacyVerifyString, legacySignString, legacyVerifyAgent, legacyUpdateAgent, verifyDocumentStandalone, legacyVerifyDocument, legacyUpdateDocument, legacyVerifySignature, legacyCreateAgreement, legacySignAgreement, legacyCreateDocument, legacyCheckAgreement, legacySignRequest, legacyVerifyResponse, legacyVerifyResponseWithAgentId, fetchRemoteKey, generateVerifyLink } = nativeBinding
 
 module.exports.JacsAgent = JacsAgent
 module.exports.hashString = hashString
 module.exports.createConfig = createConfig
+module.exports.createAgentSync = createAgentSync
 module.exports.createAgent = createAgent
 module.exports.trustAgent = trustAgent
 module.exports.listTrustedAgents = listTrustedAgents
 module.exports.untrustAgent = untrustAgent
 module.exports.isTrusted = isTrusted
 module.exports.getTrustedAgent = getTrustedAgent
+module.exports.auditSync = auditSync
 module.exports.audit = audit
-module.exports.load = load
-module.exports.signAgent = signAgent
-module.exports.verifyString = verifyString
-module.exports.signString = signString
-module.exports.verifyAgent = verifyAgent
-module.exports.updateAgent = updateAgent
+module.exports.legacyLoad = legacyLoad
+module.exports.legacySignAgent = legacySignAgent
+module.exports.legacyVerifyString = legacyVerifyString
+module.exports.legacySignString = legacySignString
+module.exports.legacyVerifyAgent = legacyVerifyAgent
+module.exports.legacyUpdateAgent = legacyUpdateAgent
 module.exports.verifyDocumentStandalone = verifyDocumentStandalone
-module.exports.verifyDocument = verifyDocument
-module.exports.updateDocument = updateDocument
-module.exports.verifySignature = verifySignature
-module.exports.createAgreement = createAgreement
-module.exports.signAgreement = signAgreement
-module.exports.createDocument = createDocument
-module.exports.checkAgreement = checkAgreement
-module.exports.signRequest = signRequest
-module.exports.verifyResponse = verifyResponse
-module.exports.verifyResponseWithAgentId = verifyResponseWithAgentId
+module.exports.legacyVerifyDocument = legacyVerifyDocument
+module.exports.legacyUpdateDocument = legacyUpdateDocument
+module.exports.legacyVerifySignature = legacyVerifySignature
+module.exports.legacyCreateAgreement = legacyCreateAgreement
+module.exports.legacySignAgreement = legacySignAgreement
+module.exports.legacyCreateDocument = legacyCreateDocument
+module.exports.legacyCheckAgreement = legacyCheckAgreement
+module.exports.legacySignRequest = legacySignRequest
+module.exports.legacyVerifyResponse = legacyVerifyResponse
+module.exports.legacyVerifyResponseWithAgentId = legacyVerifyResponseWithAgentId
 module.exports.fetchRemoteKey = fetchRemoteKey
 module.exports.generateVerifyLink = generateVerifyLink

package/koa.d.ts

@@ -0,0 +1,59 @@
+/**
+ * JACS Koa Middleware
+ *
+ * Factory-based middleware for Koa that verifies incoming JACS-signed
+ * request bodies and optionally auto-signs JSON responses.
+ *
+ * @example
+ * ```typescript
+ * import Koa from 'koa';
+ * import bodyParser from 'koa-bodyparser';
+ * import { JacsClient } from './client';
+ * import { jacsKoaMiddleware } from './koa';
+ *
+ * const client = await JacsClient.quickstart();
+ * 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' };
+ * });
+ * ```
+ */
+import type { JacsClient } from './client.js';
+export interface JacsKoaMiddlewareOptions {
+    /** Pre-initialized JacsClient instance (preferred). */
+    client?: JacsClient;
+    /** Path to jacs config file. Used only if `client` is not provided. */
+    configPath?: string;
+    /** Auto-sign JSON response bodies after next(). Default: false (opt-in). */
+    sign?: boolean;
+    /** Verify incoming POST/PUT/PATCH bodies as JACS documents. Default: true. */
+    verify?: boolean;
+    /** Allow unsigned/invalid requests to pass through instead of returning 401. Default: false. */
+    optional?: boolean;
+}
+interface KoaContext {
+    request: {
+        method: string;
+        body?: any;
+    };
+    state: Record<string, any>;
+    body: any;
+    status: number;
+    method: string;
+    type: string;
+    [key: string]: any;
+}
+/**
+ * Create JACS Koa middleware.
+ *
+ * Attaches `ctx.state.jacsClient` on every request.
+ * When `verify` is true (default), POST/PUT/PATCH bodies are verified and
+ * extracted payload is set on `ctx.state.jacsPayload`.
+ * When `sign` is true, `ctx.body` is auto-signed after downstream middleware runs.
+ */
+export declare function jacsKoaMiddleware(options?: JacsKoaMiddlewareOptions): (ctx: KoaContext, next: () => Promise<void>) => Promise<void>;
+export {};