{"_id":"@argushq/agent-sdk","name":"@argushq/agent-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@argushq/agent-sdk","version":"0.1.0","description":"Node reference implementation of the Argus Agent Protocol v1 — linking, telemetry, signed command receiver, policy pull, heartbeat. The cross-target generalisation of the WordPress Sentinel agent. Use this to build a custom Argus integration for any runti","keywords":["argus","security","agent","siem","telemetry","waf","hmac"],"license":"MIT","author":{"name":"Mind Hack, Inc."},"homepage":"https://argusmesh.app","repository":{"type":"git","url":"git+https://github.com/humphreytheodore/argus.git","directory":"packages/agent-sdk"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"engines":{"node":">=20.10.0"},"dependencies":{"ulid":"^2.3.0"},"devDependencies":{"@types/node":"^22.7.5","tsup":"^8.3.5","typescript":"^5.6.3"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup","typecheck":"tsc --noEmit","lint":"echo '(agent-sdk lint not configured yet)'"},"_id":"@argushq/agent-sdk@0.1.0","bugs":{"url":"https://github.com/humphreytheodore/argus/issues"},"_integrity":"sha512-UhxxMEYXuwpv8yjHodlo0b05ZCdfWZuQBEUaKPM25aUkhcTJg4TpI/eLnbavJAonkNBrNRQaS5N4E9E5OLd+Lw==","_resolved":"/private/tmp/claude-501/16cf91faa342c6104cccea56a99d7652/argushq-agent-sdk-0.1.0.tgz","_from":"file:argushq-agent-sdk-0.1.0.tgz","_nodeVersion":"22.14.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-UhxxMEYXuwpv8yjHodlo0b05ZCdfWZuQBEUaKPM25aUkhcTJg4TpI/eLnbavJAonkNBrNRQaS5N4E9E5OLd+Lw==","shasum":"e4015bf532b40e0a37aeda24e2f95f80c396b81f","tarball":"https://registry.npmjs.org/@argushq/agent-sdk/-/agent-sdk-0.1.0.tgz","fileCount":8,"unpackedSize":44381,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC+Dc5mVjmR7TiDWpi7oQriTzcQ9h92/P1Bsz6ZHv55LAiAVGsqvE9jtlrDjWp7YdfTGmCmoCXd7zfHAO8/M+d8TuQ=="}]},"_npmUser":{"name":"dotperson","email":"ht@humphreytheodore.com"},"directories":{},"maintainers":[{"name":"dotperson","email":"ht@humphreytheodore.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-sdk_0.1.0_1780828353126_0.1457248902540671"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-07T10:32:32.939Z","0.1.0":"2026-06-07T10:32:33.277Z","modified":"2026-06-07T10:32:33.541Z"},"maintainers":[{"name":"dotperson","email":"ht@humphreytheodore.com"}],"description":"Node reference implementation of the Argus Agent Protocol v1 — linking, telemetry, signed command receiver, policy pull, heartbeat. The cross-target generalisation of the WordPress Sentinel agent. Use this to build a custom Argus integration for any runti","homepage":"https://argusmesh.app","keywords":["argus","security","agent","siem","telemetry","waf","hmac"],"repository":{"type":"git","url":"git+https://github.com/humphreytheodore/argus.git","directory":"packages/agent-sdk"},"author":{"name":"Mind Hack, Inc."},"bugs":{"url":"https://github.com/humphreytheodore/argus/issues"},"license":"MIT","readme":"# @argushq/agent-sdk\n\nThe low-level **Argus Agent Protocol v1** client — for building a **custom in-app\nintegration** beyond the batteries-included [`@argushq/agent`](https://www.npmjs.com/package/@argushq/agent)\nmiddleware. Any Node service (a sidecar, a CI step, a worker, a non-Next framework) can\nlink to Argus, stream telemetry, receive signed commands, and sync policy over the same\nHMAC scheme the WordPress plugin uses.\n\n```bash\npnpm add @argushq/agent-sdk\n```\n\n> Building a Next.js app? Prefer **`@argushq/agent`** — one line of middleware and\n> `npx argus pair` wire everything below for you. Reach for this SDK when you need to\n> control the integration yourself.\n\n```ts\nimport { ArgusAgent, pair } from '@argushq/agent-sdk'\n\n// Headless link (or bring pre-provisioned creds).\nconst { json: creds } = await pair('https://api.argusmesh.app', token, 'https://myapp.example')\n\nconst agent = new ArgusAgent({\n  apiBase: 'https://api.argusmesh.app',     // agent plane (heartbeat / policy / commands)\n  ingestUrl: creds!.ingest_url,             // telemetry\n  siteId: creds!.site_id,\n  secret: creds!.hmac_secret,               // server-side only — never ship to a browser\n})\n\n// Telemetry\nawait agent.emit([{ type: 'error.unhandled', message: err.message, route: req.path }])\n\n// Liveness (flips the target pending → active) + policy\nawait agent.heartbeat({ agent_version: '0.1.0', enforcement_ok: true })\nconst { json: policy } = await agent.getPolicy()\n\n// Read-backs\nconst { json: findings } = await agent.getFindings()\nconst { json: incidents } = await agent.getIncidents()\n\n// Rotate the secret\nconst { json: rotated } = await agent.rotateSecret()\n```\n\n## API\n\n| Export | Purpose |\n|---|---|\n| `pair(apiBase, token, siteUrl, agentVersion?)` | Exchange an org enrolment token for credentials (creates the target). |\n| `redeem(apiBase, code)` | Exchange a browser link code for credentials (single-use). |\n| `class ArgusAgent` | `emit` · `getSelf` · `getFindings` · `getIncidents` · `getPolicy` · `putPolicy` · `heartbeat` · `rotateSecret` |\n| `verifyCommand({ rawBody, timestamp, signature, secret })` | Verify an inbound signed command (HMAC, ±300s replay, constant-time) before acting. |\n| `type EventType` | The canonical set of event `type` discriminators the gateway accepts. |\n| `newEventId()` | ULID event id. |\n\n## Command receiver\n\n```ts\nimport { verifyCommand } from '@argushq/agent-sdk'\n\nconst v = verifyCommand({\n  rawBody, timestamp: req.headers['x-argus-ts'], signature: req.headers['x-argus-sig'],\n  secret: process.env.ARGUS_HMAC_SECRET!,\n})\nif (!v.ok) return reply.code(401).send({ reason: v.reason })\n// dispatch the allow-listed action…\n```\n\n## HMAC scheme\n\nEvery signed request carries:\n\n```\nx-argus-site : <site_id>\nx-argus-ts   : epoch milliseconds\nx-argus-sig  : v1=hex(HMAC_SHA256(\"${ts}.${rawBody}\", secret))\n```\n\n±300-second replay window, computed over the **raw** body (a GET signs over `${ts}.`).\nThe site HMAC secret stays server-side.\n\n## Runnable example\n\n`src/example.ts` is a zero-dependency web-app sidecar (`node:http`) wiring CSP-report\ntelemetry, an error route, a command receiver, policy pull, and a heartbeat loop:\n\n```bash\nARGUS_API_BASE=http://localhost:8099 ARGUS_PAIR_TOKEN=<token> \\\nARGUS_SITE_URL=https://myapp.example tsx src/example.ts\n```\n\nZero runtime deps beyond `ulid` and Node's global `fetch`.\n\n## Links\n\n- [Agent Protocol v1](../../Docs/agent-protocol-v1.md)\n- [OpenAPI: agent plane](../../Docs/openapi/agent-plane.yaml) · [ingest](../../Docs/openapi/ingest.yaml)\n- [`@argushq/agent`](../agent) — the Next.js drop-in\n\n## License\n\nMIT © Mind Hack, Inc.\n","readmeFilename":"README.md","_rev":"1-2b1e55c095131c2a8ab26f456781cd0c"}