securenow 8.1.0 → 8.3.0

package/NPM_README.md

@@ -259,6 +259,49 @@ npx securenow notifications read-all
 
 ### Alerting
 
+### Revoke / kill sessions (new in 8.3)
+
+```js
+const securenow = require('securenow/sessions');
+app.use(securenow.guard());   // auto-detects NextAuth/connect.sid/JWT sessions; rejects revoked ones (401)
+// ...or check manually:
+if (securenow.isRevoked({ sessionId, userId })) return res.status(401).send('re-auth');
+```
+
+Revoke from the CLI (the SDK enforces within ~seconds, outbound-only, fail-open):
+
+```bash
+npx securenow revoke session <session-id> --reason "impossible travel"
+npx securenow revoke user <user-id> --duration 7d        # kill all of a user's sessions
+npx securenow revoke list
+```
+
+### 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/security.js

@@ -583,6 +583,88 @@ async function blocklistList(args, flags) {
   }
 }
 
+async function revokeRoute(args, flags) {
+  const sub = args[0];
+  if (sub === 'list') return revokeList(args.slice(1), flags);
+  if (sub === 'restore') return revokeRestore(args.slice(1), flags);
+  if (sub === 'session' || sub === 'user') return revokeAdd(sub, args.slice(1), flags);
+  ui.error('Usage: securenow revoke <session <id> | user <id> | list | restore <id>> [--reason "..."] [--duration 24h] [--app <key>] [--env <env>]');
+  process.exit(1);
+}
+
+async function revokeAdd(type, args, flags) {
+  requireAuth();
+  const value = args[0];
+  if (!value) {
+    ui.error(`Usage: securenow revoke ${type} <${type === 'session' ? 'session-id' : 'user-id'}> [--reason "..."] [--duration 24h] [--app <key>] [--env <env>]`);
+    process.exit(1);
+  }
+  const body = { type, value, source: 'cli' };
+  if (flags.reason) body.reason = flags.reason;
+  if (flags.duration) body.duration = flags.duration;
+  if (flags.app || flags.apps) body.applicationKey = flags.app || flags.apps;
+  if (flags.env || flags.environment) body.environment = flags.env || flags.environment;
+
+  const s = ui.spinner(`Revoking ${type} ${value}`);
+  try {
+    const data = await api.post('/revocations', body);
+    s.stop(`Revoked ${type} ${ui.truncate(value, 24)}`);
+    if (flags.json) { ui.json(data); return; }
+    const r = data.revocation || data;
+    ui.keyValue([
+      ['ID', r._id || r.id || '-'],
+      ['Type', r.type || type],
+      ['Value', r.value || value],
+      ['Scope', r.applicationKey || 'all apps'],
+      ['Expires', r.expiresAt ? new Date(r.expiresAt).toISOString() : 'never'],
+    ]);
+  } catch (err) {
+    s.fail('Failed to revoke');
+    throw err;
+  }
+}
+
+async function revokeList(args, flags) {
+  requireAuth();
+  const s = ui.spinner('Fetching revocations');
+  try {
+    const query = {};
+    if (flags.type) query.type = flags.type;
+    if (flags.status) query.status = flags.status;
+    const data = await api.get('/revocations', { query });
+    const entries = data.revocations || [];
+    s.stop(`Found ${entries.length} revocation${entries.length !== 1 ? 's' : ''}`);
+    if (flags.json) { ui.json(entries); return; }
+    console.log('');
+    ui.table(['ID', 'Type', 'Value', 'Scope', 'Expires'], entries.map((r) => [
+      ui.c.dim(ui.truncate(r._id || r.id, 12)),
+      r.type,
+      ui.truncate(r.value, 28),
+      r.applicationKey || ui.c.dim('all'),
+      r.expiresAt ? new Date(r.expiresAt).toISOString().slice(0, 16) : ui.c.dim('never'),
+    ]));
+    console.log('');
+  } catch (err) {
+    s.fail('Failed to list revocations');
+    throw err;
+  }
+}
+
+async function revokeRestore(args, flags) {
+  requireAuth();
+  const id = args[0];
+  if (!id) { ui.error('Usage: securenow revoke restore <id> [--reason "..."]'); process.exit(1); }
+  const s = ui.spinner('Restoring');
+  try {
+    const data = await api.post(`/revocations/${id}/restore`, { reason: flags.reason || '' });
+    s.stop('Revocation lifted');
+    if (flags.json) ui.json(data);
+  } catch (err) {
+    s.fail('Failed to restore');
+    throw err;
+  }
+}
+
 async function blocklistAdd(args, flags) {
   requireAuth();
   let ip = args[0];
@@ -1337,6 +1419,7 @@ module.exports = {
   blocklistAdd,
   blocklistRemove,
   blocklistStats,
+  revokeRoute,
   allowlistList,
   allowlistAdd,
   allowlistRemove,

package/cli.js

@@ -437,6 +437,18 @@ const COMMANDS = {
     },
     defaultSub: 'list',
   },
+  revoke: {
+    desc: 'Revoke sessions/users (kill stolen sessions; the SDK enforces via securenow/sessions)',
+    usage: 'securenow revoke <session <id> | user <id> | list | restore <id>> [options]',
+    flags: { reason: 'Audit reason', duration: 'Expiry, e.g. 24h or 7d (default 7d)', app: 'Scope to app key', env: 'Scope to environment', environment: 'Alias for --env', type: 'List filter: session or user', status: 'List filter: active or restored', json: 'Output as JSON' },
+    sub: {
+      session: { desc: 'Revoke a session id', usage: 'securenow revoke session <session-id> [--reason <r>] [--duration 24h] [--app <key>]', run: (a, f) => require('./cli/security').revokeRoute(['session', ...a], f) },
+      user: { desc: 'Revoke all sessions of a user id', usage: 'securenow revoke user <user-id> [--reason <r>] [--duration 24h] [--app <key>]', run: (a, f) => require('./cli/security').revokeRoute(['user', ...a], f) },
+      list: { desc: 'List active revocations', run: (a, f) => require('./cli/security').revokeRoute(['list', ...a], f) },
+      restore: { desc: 'Lift a revocation', usage: 'securenow revoke restore <id> [--reason <r>]', run: (a, f) => require('./cli/security').revokeRoute(['restore', ...a], f) },
+    },
+    defaultSub: 'list',
+  },
   allowlist: {
     desc: 'Manage IP allowlist (only allow listed IPs)',
     usage: 'securenow allowlist <subcommand> [options]',
@@ -600,6 +612,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]',
@@ -689,8 +722,8 @@ function showHelp(commandName) {
     'Detect & Respond': ['human', 'notifications', 'alerts', 'fp'],
     'Investigate': ['ip', 'forensics'],
     'Firewall': ['firewall'],
-    'Remediation': ['automation', 'ratelimit', 'blocklist', 'allowlist', 'trusted'],
-    'Telemetry': ['log', 'test-span'],
+    'Remediation': ['automation', 'ratelimit', 'blocklist', 'revoke', 'allowlist', 'trusted'],
+    '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.3.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,14 @@
       "types": "./tracing.d.ts",
       "default": "./tracing.js"
     },
+    "./events": {
+      "types": "./events.d.ts",
+      "default": "./events.js"
+    },
+    "./sessions": {
+      "types": "./sessions.d.ts",
+      "default": "./sessions.js"
+    },
     "./console-instrumentation": {
       "default": "./console-instrumentation.js"
     },
@@ -112,6 +120,10 @@
     "register.d.ts",
     "tracing.js",
     "tracing.d.ts",
+    "events.js",
+    "events.d.ts",
+    "sessions.js",
+    "sessions.d.ts",
     "console-instrumentation.js",
     "nextjs.js",
     "nextjs.d.ts",

package/sessions.d.ts

@@ -0,0 +1,27 @@
+import type { IncomingMessage, ServerResponse } from "http";
+
+export interface GuardOptions {
+  /** Extract the session id from a request. Defaults to NextAuth/connect.sid cookie or hashed Bearer token. */
+  getSessionId?: (req: IncomingMessage) => string | null | undefined;
+  /** Extract the user id from a request. Defaults to the JWT `sub` claim. */
+  getUserId?: (req: IncomingMessage) => string | null | undefined;
+  /** Custom rejection handler. Default: 401 + clears known session cookies. */
+  onRevoked?: (req: any, res: any, next: any, ctx: { sessionId: string | null; userId: string | null }) => void;
+  /** Background sync interval in ms (default 30000). */
+  syncIntervalMs?: number;
+}
+
+/** Start background revocation sync (called automatically by guard()). */
+export function start(options?: GuardOptions): void;
+
+/** Force one sync now. Best-effort; never throws. */
+export function syncOnce(): Promise<boolean>;
+
+/** Is this session/user currently revoked? */
+export function isRevoked(input: { sessionId?: string | null; userId?: string | null }): boolean;
+
+/** Express-style middleware that rejects revoked sessions/users. Fail-open. */
+export function guard(options?: GuardOptions): (req: any, res: any, next: any) => void;
+
+/** SHA-256 helper (used to hash raw session tokens consistently). */
+export function sha256(value: string): string;

package/sessions.js

@@ -0,0 +1,238 @@
+'use strict';
+
+// SecureNow session/user revocation enforcement (the "kill the stolen session"
+// half of account-takeover response).
+//
+//   const securenow = require('securenow/sessions');
+//   app.use(securenow.guard());           // auto-detects NextAuth/connect.sid/JWT sessions
+//   // ...or check manually in your auth middleware:
+//   if (securenow.isRevoked({ sessionId, userId })) return res.status(401)...
+//
+// The SDK pulls active revocations from SecureNow (outbound, ETag-cached) and
+// checks each request locally — no inbound webhook, works behind NAT, portable
+// to any language. Fail-open: a SecureNow/network outage never blocks traffic.
+
+const crypto = require('crypto');
+const appConfig = require('./app-config');
+
+let _entries = new Map(); // "type:value" -> expiryMs (0 = never)
+let _etag = null;
+let _started = false;
+let _timer = null;
+let _syncIntervalMs = 30000;
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(String(value)).digest('hex');
+}
+
+function resolveSyncTarget() {
+  try {
+    const fw = appConfig.resolveFirewallOptions();
+    const apiUrl = String((fw && fw.apiUrl) || '').replace(/\/$/, '');
+    const apiKey = fw && fw.apiKey;
+    const resolvedApp = appConfig.resolveAll();
+    const appKey = resolvedApp && resolvedApp.appKey;
+    let env = 'production';
+    try { env = appConfig.resolveDeploymentEnvironment() || 'production'; } catch {}
+    if (!apiUrl || !apiKey || !appKey) return null;
+    const url = `${apiUrl}/api/v1/revocations/sync?app=${encodeURIComponent(appKey)}&env=${encodeURIComponent(env)}`;
+    return { url, apiKey, appKey };
+  } catch {
+    return null;
+  }
+}
+
+function applyEntries(list) {
+  const next = new Map();
+  for (const e of list || []) {
+    if (!e || !e.type || !e.value) continue;
+    const exp = e.expiresAt ? Date.parse(e.expiresAt) : 0;
+    next.set(`${e.type}:${e.value}`, Number.isFinite(exp) ? exp : 0);
+  }
+  _entries = next;
+}
+
+function syncOnce() {
+  return new Promise((resolve) => {
+    const t = resolveSyncTarget();
+    if (!t) return resolve(false);
+    let parsed;
+    let lib;
+    try {
+      parsed = new (require('url').URL)(t.url);
+      lib = parsed.protocol === 'https:' ? require('https') : require('http');
+    } catch {
+      return resolve(false);
+    }
+    const headers = { Authorization: `Bearer ${t.apiKey}`, 'x-securenow-app-key': t.appKey };
+    if (_etag) headers['if-none-match'] = _etag;
+    const req = lib.request(
+      {
+        method: 'GET',
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path: parsed.pathname + parsed.search,
+        headers,
+        timeout: 5000,
+      },
+      (res) => {
+        if (res.statusCode === 304) {
+          res.resume();
+          return resolve(true);
+        }
+        const etag = res.headers.etag;
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            try {
+              const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+              applyEntries(body && body.revocations && body.revocations.entries);
+              if (etag) _etag = etag;
+            } catch {}
+            return resolve(true);
+          }
+          return resolve(false);
+        });
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => {
+      try { req.destroy(); } catch {}
+      resolve(false);
+    });
+    req.end();
+  });
+}
+
+function isExpired(exp) {
+  return exp && Date.now() > exp;
+}
+
+/**
+ * Is this session/user currently revoked? Pass whatever you have.
+ * @param {{sessionId?: string, userId?: string}} input
+ */
+function isRevoked(input) {
+  if (!input) return false;
+  const sid = input.sessionId != null ? String(input.sessionId) : null;
+  const uid = input.userId != null ? String(input.userId) : null;
+  if (sid) {
+    const e = _entries.get(`session:${sid}`);
+    if (e !== undefined && !isExpired(e)) return true;
+  }
+  if (uid) {
+    const e = _entries.get(`user:${uid}`);
+    if (e !== undefined && !isExpired(e)) return true;
+  }
+  return false;
+}
+
+function start(options = {}) {
+  if (options.syncIntervalMs) _syncIntervalMs = options.syncIntervalMs;
+  if (_started) return;
+  _started = true;
+  syncOnce();
+  _timer = setInterval(syncOnce, _syncIntervalMs);
+  if (_timer && typeof _timer.unref === 'function') _timer.unref();
+}
+
+// --- Tier-0 auto session detection (zero app code) -------------------------
+const SESSION_COOKIES = [
+  '__Secure-next-auth.session-token',
+  '__Host-next-auth.session-token',
+  'next-auth.session-token',
+  'connect.sid',
+  'session',
+  'sid',
+];
+
+function parseCookies(header) {
+  const out = {};
+  if (!header) return out;
+  for (const part of String(header).split(';')) {
+    const i = part.indexOf('=');
+    if (i > 0) out[part.slice(0, i).trim()] = part.slice(i + 1).trim();
+  }
+  return out;
+}
+
+// Mirrors how an auto-adapter emits session.id/enduser.id: hash the raw
+// cookie/token; read the JWT `sub` for the user id.
+function defaultExtract(req) {
+  let sessionId = null;
+  let userId = null;
+  const headers = req.headers || {};
+  const auth = headers.authorization || headers.Authorization;
+  if (auth && /^Bearer\s+/i.test(auth)) {
+    const token = auth.replace(/^Bearer\s+/i, '').trim();
+    if (token) {
+      sessionId = sha256(token);
+      try {
+        const seg = token.split('.')[1] || '';
+        const payload = JSON.parse(Buffer.from(seg, 'base64').toString('utf8'));
+        if (payload && payload.sub) userId = String(payload.sub);
+      } catch {}
+    }
+  }
+  if (!sessionId && headers.cookie) {
+    const cookies = parseCookies(headers.cookie);
+    for (const name of SESSION_COOKIES) {
+      if (cookies[name]) {
+        sessionId = sha256(cookies[name]);
+        break;
+      }
+    }
+  }
+  return { sessionId, userId };
+}
+
+function defaultOnRevoked(req, res) {
+  try {
+    const clears = SESSION_COOKIES.map((n) => `${n}=; Path=/; Max-Age=0; HttpOnly`);
+    if (typeof res.setHeader === 'function') res.setHeader('Set-Cookie', clears);
+  } catch {}
+  if (typeof res.status === 'function' && typeof res.json === 'function') {
+    return res.status(401).json({ error: 'Session revoked. Please sign in again.', code: 'session_revoked' });
+  }
+  res.statusCode = 401;
+  try { res.end('Session revoked'); } catch {}
+}
+
+/**
+ * Express-style middleware that rejects requests whose session/user is revoked.
+ * Starts background sync on first use. Fail-open and never throws.
+ *
+ * @param {object} [options]
+ * @param {(req)=>string} [options.getSessionId]  Custom session id extractor.
+ * @param {(req)=>string} [options.getUserId]     Custom user id extractor.
+ * @param {(req,res,next,ctx)=>void} [options.onRevoked]  Custom rejection handler.
+ * @param {number} [options.syncIntervalMs]
+ */
+function guard(options = {}) {
+  start(options);
+  const { getSessionId, getUserId } = options;
+  const onRevoked = options.onRevoked || defaultOnRevoked;
+  return function securenowSessionGuard(req, res, next) {
+    try {
+      let sessionId = null;
+      let userId = null;
+      if (getSessionId || getUserId) {
+        if (getSessionId) sessionId = getSessionId(req);
+        if (getUserId) userId = getUserId(req);
+      } else {
+        const d = defaultExtract(req);
+        sessionId = d.sessionId;
+        userId = d.userId;
+      }
+      if (isRevoked({ sessionId, userId })) {
+        return onRevoked(req, res, next, { sessionId, userId });
+      }
+    } catch {
+      /* fail-open */
+    }
+    return next();
+  };
+}
+
+module.exports = { start, syncOnce, isRevoked, guard, sha256 };