Skip to main content

AuthTools

AuthTools is the unified entry point for the event-driven tools system. It wires AuthEventBus to three optional capabilities:

  • Telemetry — persist every tracked event via ITelemetryStore
  • SSE — stream events to connected browser/server clients in real time
  • Webhooks — forward events to external HTTP endpoints with HMAC signing, or execute dynamic inbound scripts when external providers call you

See the dedicated Webhooks page for full details on both outgoing and inbound webhook configurations, including the @webhookAction decorator.

All capabilities are opt-in. Unused features have zero runtime overhead.

Quick start​

import { AuthTools, AuthEventBus, createToolsRouter } from '@nik2208/node-auth';

const bus = new AuthEventBus();

const tools = new AuthTools(bus, {
  telemetryStore: myTelemetryStore,    // optional
  webhookStore:   myWebhookStore,      // optional
  sse:            true,                // optional — enables GET /tools/stream
  sseOptions: { heartbeatIntervalMs: 15_000 },
  webhookVersion: '1',
});

// Mount the tools HTTP router
app.use('/tools', createToolsRouter(tools, {
  authMiddleware: auth.middleware(),
}));

Tracking events​

tools.track() persists an event to the telemetry store (if configured) and publishes it on the bus, which triggers any attached SSE streams and webhook deliveries.

await tools.track('identity.auth.login.success', { method: 'local' }, {
  userId: 'user-123',
  tenantId: 'tenant-abc',
  sessionId: 'sess-xyz',
  ip: req.ip,
  userAgent: req.headers['user-agent'],
});

Sending SSE notifications​

tools.notify() pushes a real-time event to all connected SSE clients subscribed to target.

tools.notify('user:user-123', { message: 'New login from Paris' }, {
  type: 'security-alert',
  userId: 'user-123',
  tenantId: 'tenant-abc',
});

Topics supported out of the box:

Topic patternDescription
globalBroadcast to all connections
tenant:{tenantId}All connections in a tenant
user:{userId}A single user
session:{sessionId}A single session
custom:{namespace}Application-defined channel

Full event flow​

AuthToolsOptions​

interface AuthToolsOptions {
  telemetryStore?: ITelemetryStore;
  webhookStore?: IWebhookStore;
  sse?: boolean;                             // default: false
  sseOptions?: { heartbeatIntervalMs?: number };
  webhookVersion?: string;                   // default: '1'
}

AuthTools API​

class AuthTools {
  constructor(bus: AuthEventBus, options?: AuthToolsOptions);

  track(eventName: string, data?: unknown, options?: TrackOptions): Promise<void>;
  notify(target: string, data?: unknown, options?: NotifyOptions): void;

  get sseManager(): SseManager | undefined;
  get eventBus(): AuthEventBus;
}