Security Agent SDK

A TypeScript SDK and CLI for automatic client registration, heartbeat, and monitoring with your Security Gateway.

This package allows clients to register themselves with your gateway, send periodic heartbeats, and ensure failover and automatic reconnection if the gateway goes down. Ideal for security-as-a-service setups where your main gateway protects client applications.

Gateways are now internal and configured via .env, so clients no longer need to specify them.

Features

• Automatic client registration with your Security Gateway
• Periodic heartbeat to indicate client is alive
• Automatic retry registration if gateway is unreachable
• Graceful shutdown handling on SIGINT or SIGTERM
• CLI and programmatic usage
• Full TypeScript support with type definitions
• Failover support for multiple gateways (configured internally)
• Gateways read dynamically from .env

Installation

Install via npm:

npm install security-agent

or using pnpm:

pnpm add security-agent

Usage

You can use the SDK either programmatically in your Node.js/TypeScript project or via the CLI.

1️⃣ Programmatic Usage

import { startSecurityAgent } from "security-agent";

startSecurityAgent({
  apiKey: "YOUR_API_KEY",              // API key from the gateway
  heartbeatInterval: 20000,            // Heartbeat interval in ms (optional, default 20000)
  autoRetry: true,                     // Automatically retry registration if gateway is down (default true)
});

How it works:

1. Registers the client with the gateway (POST /internal/register)
2. Sends heartbeat periodically (POST /internal/heartbeat)
3. Updates the gateway with client metadata and last seen timestamp
4. Automatically retries registration if the gateway is down
5. Handles graceful shutdown signals (SIGINT / SIGTERM)

2️⃣ CLI Usage

The CLI provides the same functionality without writing any code. Start the agent

npx security-agent start \
  --apiKey YOUR_API_KEY \
  --interval 20000 \
  --autoRetry

CLI Options:

| Option | Description | | ----------------- | -------------------------------------------------------------------------- | | -k, --apiKey | Required. API key issued by the gateway | | -i, --interval | Heartbeat interval in milliseconds. Default 20000 | | -r, --autoRetry | Automatically retry registration if gateway is unreachable. Default true |

| ⚠️ Gateways are now internal and read from .env. The --gateway option is no longer needed.

3️⃣ Local Testing

To test the package locally before publishing:

1. Build the package:

pnpm run build

2. Link it globally:

pnpm link

3. Run the CLI globally:

security-agent start \
  --apiKey test_key_123 \

4. Or use it in a client project locally:

npm link security-agent

Then import in your Node.js project:

import { startSecurityAgent } from "security-agent";

startSecurityAgent({
  apiKey: "test_key_123",
});

4️⃣ Multiple Gateways (Failover)

The agent automatically communicates with all internal gateways:

• If a gateway is down, it retries registration every few seconds.
• Heartbeats are sent to all gateways.
• No client-side gateway configuration is required.

5️⃣ Graceful Shutdown

The agent automatically listens for:

• SIGINT (CTRL + C)
• SIGTERM (kill signal) On shutdown, it stops sending heartbeats and logs:

👋 Security agent stopped

6️⃣ Notes

• Make sure the gateway server exposes the following endpoints:

POST /internal/register
POST /internal/heartbeat

• The agent requires Node.js 18+
• Heartbeat interval is configurable, default is 20 seconds
• API key must be valid and registered in the gateway

7️⃣ Example Flow

1. Client installs SDK via npm
2. Client imports and starts the agent:

startSecurityAgent({ apiKey: "abc123" });

3. Agent registers client with the gateway (/internal/register)
4. Agent sends heartbeat every 20 seconds (/internal/heartbeat)
5. Gateway updates the client status in memory and database
6. If a gateway goes down, the agent automatically retries

8️⃣ License

MIT