securenow 8.1.0 → 8.2.0

package/NPM_README.md

@@ -259,6 +259,32 @@ npx securenow notifications read-all
 
 ### Alerting
 
+### Emit custom security events (new in 8.2)
+
+```js
+const { track } = require('securenow/events');
+
+// Fire-and-forget — batched, async, never throws into your app.
+track('auth.login.success', {
+  userId,            // enduser.id (durable identity for correlation)
+  sessionId,         // session.id
+  ip,                // end-user IP (enriched to geo/ASN server-side)
+  attributes: { method: 'magic_link', new_device: true },
+});
+```
+
+Events become queryable by alert rules immediately (`attributes_string['event.type']`, `['enduser.id']`, `['session.id']`, `['http.client_ip']`). Non-JS apps emit the same thing with a plain POST to `/v1/events`:
+
+```
+POST https://<your-ingest-host>/v1/events
+Authorization: Bearer snk_live_...
+X-SecureNow-App-Key: <app-uuid>
+
+{ "events": [ { "type": "auth.login.success", "user_id": "u_1", "session_id": "s_1", "ip": "1.2.3.4" } ] }
+```
+
+CLI: `npx securenow event send auth.login.failure --user u_1 --ip 1.2.3.4 --attrs reason=bad_token`
+
 ```bash
 # Create a custom detection rule from your own SQL (new in 8.1)
 npx securenow alerts rules create \

package/cli/diagnostics.js

@@ -527,4 +527,51 @@ async function doctor(_args, flags) {
   process.exit(ok ? 0 : 1);
 }
 
-module.exports = { testSpan, logSend, doctor, env };
+async function eventSend(args, flags) {
+  const type = (args[0] || '').trim();
+  if (!type) {
+    ui.error('Missing event type.');
+    console.log(`  ${ui.c.bold('Usage:')} securenow event send <type> [--user <id>] [--session <id>] [--ip <ip>] [--user-agent <ua>] [--level info|warn|error] [--attrs k=v,k=v]`);
+    process.exit(1);
+  }
+
+  const cfg = resolvedConfig(flags);
+  const eventsEndpoint = `${String(cfg.instance || '').replace(/\/$/, '')}/v1/events`;
+
+  const attributes = {};
+  if (flags.attrs) {
+    for (const pair of String(flags.attrs).split(',')) {
+      const [k, ...rest] = pair.split('=');
+      if (k && rest.length) attributes[k.trim()] = rest.join('=').trim();
+    }
+  }
+
+  const ev = { type, ts: Date.now() };
+  if (flags.user) ev.user_id = String(flags.user);
+  if (flags.session) ev.session_id = String(flags.session);
+  if (flags.ip) ev.ip = String(flags.ip);
+  if (flags['user-agent']) ev.user_agent = String(flags['user-agent']);
+  if (flags.level) ev.severity = String(flags.level);
+  if (Object.keys(attributes).length) ev.attributes = attributes;
+
+  const headers = { 'Content-Type': 'application/json', ...cfg.headers };
+  const spin = ui.spinner(`Sending event to ${eventsEndpoint}`);
+  try {
+    const res = await httpRequest({ endpoint: eventsEndpoint, headers, body: JSON.stringify({ events: [ev] }) });
+    if (res.status >= 200 && res.status < 300) {
+      spin.stop(`Event accepted (HTTP ${res.status})`);
+      if (flags.json) ui.json({ ok: true, status: res.status, endpoint: eventsEndpoint, type });
+      return;
+    }
+    spin.fail(`Events ingest returned HTTP ${res.status}`);
+    if (res.body) console.log(ui.c.dim(res.body.slice(0, 500)));
+    if (flags.json) ui.json({ ok: false, status: res.status, body: res.body });
+    process.exit(1);
+  } catch (err) {
+    spin.fail(`Failed: ${err.message}`);
+    if (flags.json) ui.json({ ok: false, error: err.message });
+    process.exit(1);
+  }
+}
+
+module.exports = { testSpan, logSend, eventSend, doctor, env };

package/cli.js

@@ -600,6 +600,27 @@ const COMMANDS = {
     },
     defaultSub: 'send',
   },
+  event: {
+    desc: 'Emit a custom security event to SecureNow (for scripts, testing, non-JS apps)',
+    usage: 'securenow event send <type> [--user <id>] [--session <id>] [--ip <ip>] [--attrs k=v,k=v]',
+    sub: {
+      send: {
+        desc: 'Send a single custom event to the /v1/events ingest',
+        flags: {
+          env: 'Deployment environment for this event (defaults to credentials file)',
+          environment: 'Alias for --env',
+          user: 'End-user / account id (enduser.id)',
+          session: 'Session id (session.id)',
+          ip: 'End-user client IP',
+          'user-agent': 'End-user agent string',
+          level: 'Severity (trace|debug|info|warn|error|fatal)',
+          attrs: 'Comma-separated key=value attributes',
+        },
+        run: (a, f) => require('./cli/diagnostics').eventSend(a, f),
+      },
+    },
+    defaultSub: 'send',
+  },
   'test-span': {
     desc: 'Emit a test span to verify collector connectivity',
     usage: 'securenow test-span [<span-name>] [--env local|production]',
@@ -690,7 +711,7 @@ function showHelp(commandName) {
     'Investigate': ['ip', 'forensics'],
     'Firewall': ['firewall'],
     'Remediation': ['automation', 'ratelimit', 'blocklist', 'allowlist', 'trusted'],
-    'Telemetry': ['log', 'test-span'],
+    'Telemetry': ['log', 'event', 'test-span'],
     'Utilities': ['redact', 'cidr', 'doctor', 'env', 'mcp'],
     'Settings': ['instances', 'config', 'version'],
   };

package/events.d.ts

@@ -0,0 +1,29 @@
+export interface TrackProps {
+  /** End-user / account identifier (durable identity for correlation). */
+  userId?: string | number;
+  /** Session identifier (finer-grained than userId). */
+  sessionId?: string | number;
+  /** End-user client IP as seen by your app (enriched to geo/ASN server-side). */
+  ip?: string;
+  /** End-user agent string. */
+  userAgent?: string;
+  /** Severity hint. Defaults to "info". */
+  severity?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+  /** Event time in epoch ms. Defaults to now. */
+  ts?: number;
+  /** Arbitrary structured attributes (string/number/boolean values). */
+  attributes?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Emit a custom security event to SecureNow. Fire-and-forget: returns
+ * immediately, batches in the background, and never throws into your app.
+ *
+ * @example
+ * import { track } from "securenow/events";
+ * track("auth.login.success", { userId, sessionId, ip, attributes: { method: "magic_link" } });
+ */
+export function track(type: string, props?: TrackProps): void;
+
+/** Force a flush of any buffered events. Best-effort; never throws. */
+export function flush(): Promise<unknown>;

package/events.js

@@ -0,0 +1,160 @@
+'use strict';
+
+// SecureNow custom events — a tiny, batched, fire-and-forget emitter.
+//
+//   const { track } = require('securenow/events');
+//   track('auth.login.success', { userId, sessionId, ip, attributes: { method: 'magic_link' } });
+//
+// Design goals:
+//   - Never throw into the caller. A SecureNow/network outage must not affect
+//     the app's request path. Events are advisory.
+//   - Non-blocking: events are buffered and flushed asynchronously in batches.
+//   - Bounded memory: the buffer is capped; oldest events drop on overflow.
+//   - Reuses the SDK's resolved runtime config (app key + auth headers +
+//     endpoint), so there is nothing extra to configure.
+
+const appConfig = require('./app-config');
+
+const MAX_BUFFER = 1000; // hard cap on queued events
+const MAX_BATCH = 100; // events sent per flush
+const FLUSH_INTERVAL_MS = 2000;
+const POST_TIMEOUT_MS = 5000;
+
+let buffer = [];
+let timer = null;
+let target = null;
+let targetResolved = false;
+
+function resolveTarget() {
+  if (targetResolved) return target;
+  targetResolved = true;
+  try {
+    const endpoints = appConfig.resolveEndpoints();
+    const base = String((endpoints && endpoints.endpointBase) || '').replace(/\/$/, '');
+    if (!base) {
+      target = null;
+      return null;
+    }
+    const headers = Object.assign({ 'Content-Type': 'application/json' }, (endpoints && endpoints.headers) || {});
+    // Without an app key + auth we can't attribute events; stay silent.
+    const hasAppKey = headers['x-securenow-app-key'] || headers['X-SecureNow-App-Key'];
+    if (!hasAppKey) {
+      target = null;
+      return null;
+    }
+    target = { url: `${base}/v1/events`, headers };
+  } catch {
+    target = null;
+  }
+  return target;
+}
+
+function post(t, payload) {
+  return new Promise((resolve) => {
+    let parsed;
+    let lib;
+    try {
+      parsed = new (require('url').URL)(t.url);
+      lib = parsed.protocol === 'https:' ? require('https') : require('http');
+    } catch {
+      return resolve(false);
+    }
+    let body;
+    try {
+      body = Buffer.from(JSON.stringify(payload));
+    } catch {
+      return resolve(false);
+    }
+    const req = lib.request(
+      {
+        method: 'POST',
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path: parsed.pathname + parsed.search,
+        headers: Object.assign({ 'Content-Length': body.length }, t.headers),
+        timeout: POST_TIMEOUT_MS,
+      },
+      (res) => {
+        res.on('data', () => {});
+        res.on('end', () => resolve(res.statusCode >= 200 && res.statusCode < 300));
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => {
+      try { req.destroy(); } catch {}
+      resolve(false);
+    });
+    try {
+      req.write(body);
+      req.end();
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+function scheduleFlush() {
+  if (timer) return;
+  timer = setTimeout(flush, FLUSH_INTERVAL_MS);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+}
+
+function flush() {
+  if (timer) {
+    clearTimeout(timer);
+    timer = null;
+  }
+  if (!buffer.length) return Promise.resolve();
+  const t = resolveTarget();
+  if (!t) {
+    buffer = []; // not configured to emit — drop silently
+    return Promise.resolve();
+  }
+  const batch = buffer.splice(0, MAX_BATCH);
+  const p = post(t, { events: batch }).catch(() => false);
+  if (buffer.length) scheduleFlush();
+  return p;
+}
+
+function normalizeEvent(type, props) {
+  if (!type || typeof type !== 'string') return null;
+  const ev = { type, ts: (props && Number(props.ts)) || Date.now() };
+  if (props) {
+    if (props.userId != null) ev.user_id = String(props.userId);
+    if (props.sessionId != null) ev.session_id = String(props.sessionId);
+    if (props.ip != null) ev.ip = String(props.ip);
+    if (props.userAgent != null) ev.user_agent = String(props.userAgent);
+    if (props.severity) ev.severity = String(props.severity);
+    if (props.attributes && typeof props.attributes === 'object' && !Array.isArray(props.attributes)) {
+      ev.attributes = props.attributes;
+    }
+  }
+  return ev;
+}
+
+/**
+ * Emit a custom event. Fire-and-forget — returns immediately, never throws.
+ * @param {string} type        Event type, e.g. "auth.login.success".
+ * @param {object} [props]      { userId, sessionId, ip, userAgent, severity, ts, attributes }
+ */
+function track(type, props = {}) {
+  try {
+    const ev = normalizeEvent(type, props);
+    if (!ev) return;
+    buffer.push(ev);
+    if (buffer.length > MAX_BUFFER) buffer.splice(0, buffer.length - MAX_BUFFER); // drop oldest
+    if (buffer.length >= MAX_BATCH) flush();
+    else scheduleFlush();
+  } catch {
+    /* never throw into the app */
+  }
+}
+
+// Best-effort flush so buffered events aren't lost on a clean shutdown.
+try {
+  process.once('beforeExit', () => {
+    try { flush(); } catch {}
+  });
+} catch {}
+
+module.exports = { track, flush };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securenow",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "description": "OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt - Send traces and logs to any OTLP-compatible backend",
   "type": "commonjs",
   "main": "register.js",
@@ -50,6 +50,10 @@
       "types": "./tracing.d.ts",
       "default": "./tracing.js"
     },
+    "./events": {
+      "types": "./events.d.ts",
+      "default": "./events.js"
+    },
     "./console-instrumentation": {
       "default": "./console-instrumentation.js"
     },
@@ -112,6 +116,8 @@
     "register.d.ts",
     "tracing.js",
     "tracing.d.ts",
+    "events.js",
+    "events.d.ts",
     "console-instrumentation.js",
     "nextjs.js",
     "nextjs.d.ts",