@esign-ai/veriagent-core

VeriAgent Core 是面向 Node.js 集成方的核心运行时 SDK，提供智能体身份安装、本地证书状态查询、标准签名对象生成、标准验签和审计上报能力。

功能概览

| 能力 | 说明 | |---|---| | 身份安装 | 通过浏览器授权完成 VeriAgent 智能体初始化和证书安装 | | 状态查询 | 查看本地安装状态、证书文件和远端状态 | | 标准签名 | 使用本地证书生成 VeriAgent 标准 signedObject | | 标准验签 | 将标准 signedObject 提交到 VeriAgent 后端验签 | | 审计上报 | 对 Agent 工具调用等事件生成签名并上报 |

环境要求

| 项 | 要求 | |---|---| | Node.js | 18 或以上 | | 浏览器 | 安装流程需要用户打开 VeriAgent 授权页面 | | 后端 | 可访问 VeriAgent API | | 运行时依赖 | @esign-ai/veriagent-trust |

安装

npm install @esign-ai/veriagent-core

快速开始

const { createRuntime } = require('@esign-ai/veriagent-core')

async function main() {
  const runtime = createRuntime({
    clientId: process.env.VERIAGENT_CLIENT_ID,
    terminalType: 'YOUR_INTEGRATION',
    installContext: {
      profile: 'prod',
    },
  })

  const status = await runtime.status()
  if (!status.certificateFile) {
    await runtime.install()
  }

  const signResult = await runtime.signStandardObject({
    eventType: 'business_event',
    action: 'manual_sign',
    payload: {
      bizId: 'ct_123',
      amount: 12800,
    },
    context: {
      hostType: 'node-service',
      traceId: 'trace_001',
    },
  })

  const verifyResult = await runtime.verifyStandardObject({
    signedObject: signResult.signedObject,
  })

  console.log(signResult.signedObject)
  console.log(verifyResult.verified)
}

main().catch(error => {
  console.error(error)
  process.exit(1)
})

配置项

| 配置 | 环境变量 | 默认值 | |---|---|---| | 本地数据目录 | VERIAGENT_PLUGIN_HOME | ~/.veriagent-plugin | | API 地址 | VERIAGENT_API_BASE_URL | 随安装环境 | | 门户地址 | VERIAGENT_PORTAL_BASE_URL | 随安装环境 | | Client ID | VERIAGENT_CLIENT_ID | 空 | | 终端类型 | VERIAGENT_TERMINAL_TYPE | 空 | | 实例名称 | VERIAGENT_INSTANCE_NAME | 当前主机名 | | 安装环境 | VERIAGENT_INSTALL_PROFILE | 自动解析 | | HTTP 超时 | VERIAGENT_HTTP_TIMEOUT_MS | 10000 |

Runtime API

const { createRuntime } = require('@esign-ai/veriagent-core')

const runtime = createRuntime(options)

| 方法 | 说明 | |---|---| | runtime.install({ reset }) | 一次性推进安装流程 | | runtime.beginAuthorization({ reset }) | 创建授权会话，返回浏览器授权链接 | | runtime.checkAuthorizationOnce() | 轮询一次授权状态 | | runtime.stepOnboarding() | 推进一次证书申请和下载状态 | | runtime.getInstallState() | 查看安装阶段快照 | | runtime.status() | 查询本地与远端状态 | | runtime.listAgents() | 列出本地智能体材料 | | runtime.reset() | 清理本地运行状态 | | runtime.getRuntimeConfig() | 查看当前运行时配置 | | runtime.signStandardObject(input) | 生成标准签名对象 | | runtime.verifyStandardObject(input) | 验证标准签名对象 | | runtime.reportAgentAuditEvent(event) | 上报 Agent 审计事件 |

安装流程

阻塞式安装：

const result = await runtime.install()

分步安装：

let step = await runtime.beginAuthorization()
console.log(step.verificationUriComplete || step.actionUrl)

while (!step.terminal && step.status !== 'completed') {
  await new Promise(resolve => setTimeout(resolve, step.nextPollAfterMs || 3000))
  step = await runtime.stepOnboarding()
}

安装完成后，runtime.status() 应返回本地 agentId 和 certificateFile。

标准签名

signStandardObject() 至少需要 eventType、action 和结构化 payload。

const signResult = await runtime.signStandardObject({
  eventType: 'business_event',
  action: 'manual_sign',
  payload: {
    bizId: 'ct_123',
  },
  context: {
    hostType: 'node-service',
    traceId: 'trace_001',
  },
})

返回结构：

{
  "requestId": "req_xxx",
  "signedObject": {
    "schemaVersion": "1.0",
    "eventType": "business_event",
    "action": "manual_sign",
    "payload": {
      "bizId": "ct_123"
    },
    "payloadHash": "sha256...",
    "signedAt": "2026-07-02T00:00:00.000Z",
    "certificateSerialNo": "cert_xxx",
    "signatureAlgorithm": "RSA-SHA256",
    "signature": "base64...",
    "extensions": {
      "agentId": "agent_xxx",
      "hostType": "node-service",
      "traceId": "trace_001"
    }
  }
}

标准验签

const verifyResult = await runtime.verifyStandardObject({
  signedObject: signResult.signedObject,
})

常用返回字段：

| 字段 | 说明 | |---|---| | verified | 总体验签结果 | | signatureVerified | 签名值是否可验证 | | payloadHashVerified | payload 摘要是否一致 | | certificateVerified | 证书是否匹配且有效 | | mismatchedFields | 不一致字段列表 | | issues | 验签问题列表 |

签名对象规则

| 字段 | 是否参与签名 | |---|---| | schemaVersion、eventType、action | 是 | | payloadHash、signedAt、certificateSerialNo | 是 | | signatureAlgorithm | 是 | | payload | 通过 payloadHash 间接参与 | | extensions | 否 |

数据链路：

业务 payload
  -> payloadHash
  -> 本地证书私钥签名
  -> signedObject
  -> 后端按 certificateSerialNo 验签

审计上报

await runtime.reportAgentAuditEvent({
  framework: 'custom',
  sessionId: 'session_001',
  runId: 'run_001',
  toolCallId: 'tool_001',
  callType: 'tool',
  callName: 'business_tool',
  status: 'success',
  occurredAt: new Date().toISOString(),
})

审计事件会使用本地智能体证书签名后上报。

本地数据

默认本地目录：

~/.veriagent-plugin/
  state.json
  agents/
    <agentId>/
      materials.json
      public-key.pem
      request.csr
      certificate.json
      certificates/
        certificate.pem

敏感字段会优先存储在系统密钥链中，不直接写入 state.json。

注意事项

| 事项 | 说明 | |---|---| | 先安装再签名 | 没有本地证书材料时无法签名 | | payload | 必须是结构化 JSON 对象 | | certificateSerialNo | 标准签名对象显式携带，后端按它查证书 | | extensions | 只放追踪字段，不参与签名覆盖 | | 跨端验签 | 只要对象符合 VeriAgent 标准签名规范即可验签 | | 文件签名 | Core 只生成 signedObject，文件落盘由上层插件处理 |