Add track() API for custom event tracking + config updates via SSE

docs/track.md

@@ -0,0 +1,48 @@
+# Tracking events
+
+`track` lets you record things happening in your app — like failed logins, signups, or password resets. Zen sends these to Aikido so patterns can be detected, like someone failing to log in 50 times in a minute.
+
+```js
+const Zen = require("@aikidosec/firewall");
+
+app.post("/login", async (req, res) => {
+  const user = await authenticate(req.body.username, req.body.password);
+
+  if (!user) {
+    Zen.track("user.login_failed");
+    return res.status(401).json({ error: "Invalid credentials" });
+  }
+
+  Zen.setUser({ id: user.id });
+  Zen.track("user.login_succeeded");
+  res.json({ token: createToken(user) });
+});
+```
+
+Zen automatically picks up the IP address, user agent, and current user (if you called [`setUser`](./user.md)) from the request — you don't need to pass those yourself.
+
+## More examples
+
+```js
+Zen.track("user.signed_up");
+Zen.track("user.password_reset_requested");
+Zen.track("plan.invite_sent");
+Zen.track("payment.failed");
+```
+
+## Naming events
+
+Use lowercase with dots to group related events:
+
+- `user.login_failed`
+- `user.login_succeeded`
+- `user.signed_up`
+- `user.password_reset_requested`
+- `payment.failed`
+- `plan.invite_sent`
+
+## Things to know
+
+`track` only works inside an HTTP request. If you call it in a background job or a script, nothing gets sent and you'll see a warning in the console.
+
+If you haven't called `setUser` yet, the event still goes through — it just won't have a user ID attached.

end2end/server/app.ts

@@ -10,6 +10,8 @@ import { updateConfig } from "./src/handlers/updateConfig.ts";
 import { lists } from "./src/handlers/lists.ts";
 import { updateIPLists } from "./src/handlers/updateLists.ts";
 import { realtimeConfig } from "./src/handlers/realtimeConfig.ts";
+import { stream, disconnectStreams } from "./src/handlers/stream.ts";
+import { deleteApp } from "./src/handlers/deleteApp.ts";
 
 const app = express();
 app.set("trust proxy", false);
@@ -24,6 +26,8 @@ app.post("/api/runtime/config", checkToken, updateConfig);
 
 // Realtime polling endpoint
 app.get("/config", checkToken, realtimeConfig);
+app.get("/api/runtime/stream", checkToken, stream);
+app.post("/api/runtime/stream/disconnect", checkToken, disconnectStreams);
 
 app.get("/api/runtime/events", checkToken, listEvents);
 app.post("/api/runtime/events", checkToken, captureEvent);
@@ -32,6 +36,7 @@ app.get("/api/runtime/firewall/lists", checkToken, lists);
 app.post("/api/runtime/firewall/lists", checkToken, updateIPLists);
 
 app.post("/api/runtime/apps", createApp);
+app.delete("/api/runtime/apps", checkToken, deleteApp);
 
 app.listen(port, () => {
   console.log(`Server is running on port ${port}`);

end2end/server/src/handlers/deleteApp.ts

@@ -0,0 +1,14 @@
+import type { Response } from "express";
+import { removeApp } from "../zen/apps.ts";
+import { closeStreams } from "./stream.ts";
+import type { ZenRequest } from "../types.ts";
+
+export function deleteApp(req: ZenRequest, res: Response) {
+  if (!req.zenApp) {
+    throw new Error("App is missing");
+  }
+
+  removeApp(req.zenApp);
+  closeStreams(req.zenApp.id);
+  res.json({ ok: true });
+}

end2end/server/src/handlers/stream.ts

@@ -0,0 +1,64 @@
+import type { Response } from "express";
+import { getAppConfig, configEvents } from "../zen/config.ts";
+import type { ZenRequest } from "../types.ts";
+
+const connections = new Map<number, Set<Response>>();
+
+export function stream(req: ZenRequest, res: Response) {
+  if (!req.zenApp) {
+    throw new Error("App is missing");
+  }
+
+  const app = req.zenApp;
+
+  if (!connections.has(app.id)) {
+    connections.set(app.id, new Set());
+  }
+  connections.get(app.id)!.add(res);
+
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+  });
+
+  function sendConfig() {
+    const config = getAppConfig(app);
+    const data = { serviceId: app.id, configUpdatedAt: config.configUpdatedAt };
+    res.write(`event: config-updated\ndata: ${JSON.stringify(data)}\n\n`);
+  }
+
+  sendConfig();
+
+  const eventName = `config-updated:${app.id}`;
+  configEvents.on(eventName, sendConfig);
+
+  const ping = setInterval(() => {
+    res.write(": ping\n\n");
+  }, 30_000);
+
+  req.on("close", () => {
+    connections.get(app.id)?.delete(res);
+    configEvents.off(eventName, sendConfig);
+    clearInterval(ping);
+  });
+}
+
+export function closeStreams(appId: number) {
+  const appConnections = connections.get(appId);
+  if (appConnections) {
+    for (const conn of appConnections) {
+      conn.end();
+    }
+    appConnections.clear();
+  }
+}
+
+export function disconnectStreams(req: ZenRequest, res: Response) {
+  if (!req.zenApp) {
+    throw new Error("App is missing");
+  }
+
+  closeStreams(req.zenApp.id);
+  res.json({ ok: true });
+}

end2end/server/src/zen/apps.ts

@@ -6,7 +6,7 @@ export type App = {
   configUpdatedAt: number;
 };
 
-const apps: App[] = [];
+let apps: App[] = [];
 
 let id = 1;
 export function createApp(): string {
@@ -20,6 +20,10 @@ export function createApp(): string {
   return token;
 }
 
+export function removeApp(app: App): void {
+  apps = apps.filter((a) => a.id !== app.id);
+}
+
 export function getByToken(token: string): App | undefined {
   return apps.find((app) => {
     if (app.token.length !== token.length) {

end2end/server/src/zen/config.ts

@@ -1,5 +1,8 @@
+import { EventEmitter } from "node:events";
 import type { App } from "./apps.ts";
 
+export const configEvents = new EventEmitter();
+
 type AppConfig = {
   success: boolean;
   serviceId: number;
@@ -53,6 +56,7 @@ export function updateAppConfig(app: App, newConfig: Partial<AppConfig>) {
     ...newConfig,
     configUpdatedAt: Date.now(),
   };
+  configEvents.emit(`config-updated:${app.id}`);
   return true;
 }
 

end2end/tests-new/heartbeat.test.mjs

@@ -90,7 +90,7 @@ test("It reports own http requests in heartbeat events", async () => {
           {
             hostname: "localhost",
             port: 5874,
-            hits: 3,
+            hits: 4,
           },
         ],
         agent: {

end2end/tests-new/hono-pg-esm-outbound.test.mjs

@@ -132,6 +132,8 @@ test("blockNewOutgoingRequests is true", async () => {
       domains: [
         { hostname: "ssrf-redirects.testssandbox.com", mode: "block" },
         { hostname: "aikido.dev", mode: "allow" },
+        // Otherwise we cannot communicate with the mock server
+        { hostname: "localhost", mode: "allow" },
       ],
     }),
   });