Node SDK · Behaviors worth knowing

Empty action is a no-op

Events with no action set are dropped at send time. Useful when you want the middleware to attach an event to every request and let handlers conditionally opt out. Set action only when something audit-worthy happens.

Dropping an unnamed event is a deliberate opt-out for an outcome that is not audit-worthy, not a way to skip failures. The difference is whether an auditor would want to see the exit path.

A read that found nothing, or a malformed request that reached no resource, is not audit-worthy: leave action unset. That is what the handler below does on its 404.

A failed attempt at an audit-worthy action is the opposite. A denied authorization, a rejected payment, an invite that errored: all of those must be recorded, which means naming the event before the early return that handles them.

app.get("/api/secrets/:id", (req, res) => {
    const s = vault.get(req.params.id);
    if (!s) {
        res.status(404).send("not found");
        return;  // action never set → event silently dropped
    }
    req.event!.action = "secret.read";
    req.event!.target = { type: "secret", id: s.id };
    res.json(s);
});

Naming an event whose target does not exist yet

When the target's ID only exists after the operation succeeds, name the event anyway and backfill the ID. Moving the naming below the error return is what silently drops the failure.

app.post("/api/members", async (req, res) => {
    req.event!.action = "member.invited";
    req.event!.target = { type: "user" };  // no ID yet, and that is fine

    let u;
    try {
        u = await members.invite(req.body);
    } catch (err) {
        res.status(500).send("invite failed");
        return;                             // recorded, result filled by the middleware
    }
    req.event!.target!.id = u.id;           // backfilled on the success path
    res.json(u);
});

An event whose target has a type but no id is still a useful audit record: it says who tried to do what, and that it failed. An event that was never named says nothing at all.

The rule generalizes past target.id. Any field you cannot populate until the operation succeeds gets assigned after the error return, never used as a reason to delay naming the event.

record() is non-blocking

record() enqueues the event on the in-memory buffer and returns immediately. The background loop handles the HTTP call on the next flush. Don't await audit acks in critical paths; awaiting buys you nothing because the network call hasn't started yet.

const start = performance.now();
rec.record(e);
console.log(performance.now() - start);  // sub-millisecond — no network call

Caller-set fields take precedence

The middleware auto-populates result from the response status. If you set result yourself, that wins. Useful for anti-enumeration handlers that return the same HTTP status for different audit outcomes.

app.get("/api/secrets/:id", (req, res) => {
    const me = actor(req)!;
    const id = req.params.id;
    req.event!.action = "secret.reveal";
    req.event!.target = { type: "secret", id };

    const s = vault.get(id);
    if (!s) {
        res.status(404).send("not found");  // genuinely doesn't exist
        return;                              // middleware records result: { status: "error", code: 404 }
    }
    if (s.tenantId !== me.tenantId) {
        // Return 404 instead of 403 so attackers can't probe for
        // secret IDs in other tenants. The user-facing response can't
        // tell the two cases apart — but the audit log should.
        req.event!.result = { status: "denied", code: 403, message: "cross-tenant access" };
        res.status(404).send("not found");
        return;
    }
    res.json({ value: s.value });
});