@argushq/agent-sdk

The low-level Argus Agent Protocol v1 client — for building a custom in-app integration beyond the batteries-included @argushq/agent middleware. Any Node service (a sidecar, a CI step, a worker, a non-Next framework) can link to Argus, stream telemetry, receive signed commands, and sync policy over the same HMAC scheme the WordPress plugin uses.

pnpm add @argushq/agent-sdk

Building a Next.js app? Prefer @argushq/agent — one line of middleware and npx argus pair wire everything below for you. Reach for this SDK when you need to control the integration yourself.

import { ArgusAgent, pair } from '@argushq/agent-sdk'

// Headless link (or bring pre-provisioned creds).
const { json: creds } = await pair('https://api.argusmesh.app', token, 'https://myapp.example')

const agent = new ArgusAgent({
  apiBase: 'https://api.argusmesh.app',     // agent plane (heartbeat / policy / commands)
  ingestUrl: creds!.ingest_url,             // telemetry
  siteId: creds!.site_id,
  secret: creds!.hmac_secret,               // server-side only — never ship to a browser
})

// Telemetry
await agent.emit([{ type: 'error.unhandled', message: err.message, route: req.path }])

// Liveness (flips the target pending → active) + policy
await agent.heartbeat({ agent_version: '0.1.0', enforcement_ok: true })
const { json: policy } = await agent.getPolicy()

// Read-backs
const { json: findings } = await agent.getFindings()
const { json: incidents } = await agent.getIncidents()

// Rotate the secret
const { json: rotated } = await agent.rotateSecret()

API

| Export | Purpose | |---|---| | pair(apiBase, token, siteUrl, agentVersion?) | Exchange an org enrolment token for credentials (creates the target). | | redeem(apiBase, code) | Exchange a browser link code for credentials (single-use). | | class ArgusAgent | emit · getSelf · getFindings · getIncidents · getPolicy · putPolicy · heartbeat · rotateSecret | | verifyCommand({ rawBody, timestamp, signature, secret }) | Verify an inbound signed command (HMAC, ±300s replay, constant-time) before acting. | | type EventType | The canonical set of event type discriminators the gateway accepts. | | newEventId() | ULID event id. |

Command receiver

import { verifyCommand } from '@argushq/agent-sdk'

const v = verifyCommand({
  rawBody, timestamp: req.headers['x-argus-ts'], signature: req.headers['x-argus-sig'],
  secret: process.env.ARGUS_HMAC_SECRET!,
})
if (!v.ok) return reply.code(401).send({ reason: v.reason })
// dispatch the allow-listed action…

HMAC scheme

Every signed request carries:

x-argus-site : <site_id>
x-argus-ts   : epoch milliseconds
x-argus-sig  : v1=hex(HMAC_SHA256("${ts}.${rawBody}", secret))

±300-second replay window, computed over the raw body (a GET signs over ${ts}.). The site HMAC secret stays server-side.

Runnable example

src/example.ts is a zero-dependency web-app sidecar (node:http) wiring CSP-report telemetry, an error route, a command receiver, policy pull, and a heartbeat loop:

ARGUS_API_BASE=http://localhost:8099 ARGUS_PAIR_TOKEN=<token> \
ARGUS_SITE_URL=https://myapp.example tsx src/example.ts

Zero runtime deps beyond ulid and Node's global fetch.

Links

• Agent Protocol v1
• OpenAPI: agent plane · ingest
• @argushq/agent — the Next.js drop-in

License

MIT © Mind Hack, Inc.