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.

library/agent/Agent.ts

@@ -13,6 +13,7 @@ import type {
   DetectedAttack,
   DetectedAttackWave,
 } from "./api/Event";
+import { sendUserEvent, type UserEvent } from "./api/UserEventsAPI";
 import { Token } from "./api/Token";
 import { Kind } from "./Attack";
 import { Endpoint } from "./Config";
@@ -712,4 +713,15 @@ export class Agent {
       this.pendingEvents.onAPICall(promise);
     }
   }
+
+  onTrackEvent(event: UserEvent) {
+    if (!this.token) {
+      return;
+    }
+
+    const promise = sendUserEvent(this.token, event).catch(() => {
+      this.logger.log("Failed to report tracked event");
+    });
+    this.pendingEvents.onAPICall(promise);
+  }
 }

library/agent/api/UserEventsAPI.ts

@@ -0,0 +1,26 @@
+import { fetch } from "../../helpers/fetch";
+import { getRealtimeURL } from "../realtime/getRealtimeURL";
+import type { Token } from "./Token";
+
+export type UserEvent = {
+  name: string;
+  userId: string | undefined;
+  ipAddress: string | undefined;
+  userAgent: string | undefined;
+};
+
+export async function sendUserEvent(
+  token: Token,
+  event: UserEvent
+): Promise<void> {
+  await fetch({
+    url: new URL(`${getRealtimeURL().toString()}api/runtime/events/user`),
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: token.asString(),
+    },
+    body: JSON.stringify(event),
+    timeoutInMS: 5000,
+  });
+}

library/agent/context/track.ts

@@ -0,0 +1,48 @@
+import { getInstance } from "../AgentSingleton";
+import { ContextStorage } from "./ContextStorage";
+
+export function track(eventName: string): void {
+  const agent = getInstance();
+
+  if (!agent) {
+    return;
+  }
+
+  if (typeof eventName !== "string" || eventName.length === 0) {
+    agent.log(`track(...) expects a non-empty string as event name.`);
+    return;
+  }
+
+  const context = ContextStorage.getStore();
+  if (!context) {
+    logWarningTrackCalledWithoutContext();
+    return;
+  }
+
+  const userAgent =
+    typeof context.headers["user-agent"] === "string"
+      ? context.headers["user-agent"]
+      : undefined;
+
+  agent.onTrackEvent({
+    name: eventName,
+    userId: context.user?.id,
+    ipAddress: context.remoteAddress,
+    userAgent,
+  });
+}
+
+let loggedWarningTrackCalledWithoutContext = false;
+
+function logWarningTrackCalledWithoutContext() {
+  if (loggedWarningTrackCalledWithoutContext) {
+    return;
+  }
+
+  // oxlint-disable-next-line no-console
+  console.warn(
+    "track(...) was called without a context. The event will not be tracked. Make sure to call track(...) within an HTTP request."
+  );
+
+  loggedWarningTrackCalledWithoutContext = true;
+}

library/index.ts

@@ -1,6 +1,7 @@
 import isFirewallSupported from "./helpers/isFirewallSupported";
 import shouldEnableFirewall from "./helpers/shouldEnableFirewall";
 import { setUser } from "./agent/context/user";
+import { track } from "./agent/context/track";
 import { markUnsafe } from "./agent/context/markUnsafe";
 import { shouldBlockRequest } from "./middleware/shouldBlockRequest";
 import { addExpressMiddleware } from "./middleware/express";
@@ -58,6 +59,7 @@ if (!isNewHookSystemUsed()) {
 
 export {
   setUser,
+  track,
   markUnsafe,
   shouldBlockRequest,
   addExpressMiddleware,
@@ -77,6 +79,7 @@ export {
 // e.g. import Zen from '@aikidosec/firewall'; would not work without this, as Zen.setUser would be undefined
 export default {
   setUser,
+  track,
   markUnsafe,
   shouldBlockRequest,
   addExpressMiddleware,