@keverdjs/node

Server-side Node.js SDK for Keverd. Verify browser/mobile event_ids and handle signed webhooks.

Node 18+ · zero runtime dependencies · works with Express and any Node backend.

Install

npm install @keverdjs/node

Quick start

import { Keverd } from "@keverdjs/node";

const keverd = new Keverd({
  secretKey: process.env.KEVERD_SECRET_KEY!, // kv_sk_live_… or kv_sk_test_…
});

// eventId comes from the browser/mobile SDK after fingerprinting
const result = await keverd.verify(eventId);

if (result.action === "block") {
  // reject the request
} else if (result.action === "allow") {
  // continue
}

verify() maps to POST /v2/verify and is the only billable decision read. Keep secret keys on the server.

Express example

import express from "express";
import { Keverd } from "@keverdjs/node";

const app = express();
const keverd = new Keverd({ secretKey: process.env.KEVERD_SECRET_KEY! });

app.post("/login", express.json(), async (req, res) => {
  const { eventId, email, password } = req.body;
  const risk = await keverd.verify(eventId);

  if (risk.action === "block") {
    return res.status(403).json({ error: "Blocked", reasons: risk.reasons });
  }

  // …authenticate user…
  res.json({ ok: true, visitorId: risk.visitor_id });
});

Webhooks (optional)

Sync verify() is enough for most flows. Configure a webhook in the dashboard when you want push delivery (fan-out to other services, or future async updates).

app.post(
  "/webhooks/keverd",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const event = keverd.webhooks.constructEvent(
      req.body, // raw Buffer / string — do not parse first
      req.headers["x-keverd-signature"] as string,
      process.env.KEVERD_WEBHOOK_SECRET!, // whsec_…
    );

    if (event.type === "verification.completed") {
      const verification = event.data.object;
      // same shape as verify()
    }

    res.sendStatus(200);
  },
);

API

| Method | Description | |--------|-------------| | new Keverd({ secretKey, baseUrl?, timeoutMs? }) | Create a client | | keverd.verify(eventId) | Billable verify → risk decision + signals | | keverd.webhooks.constructEvent(payload, signature, secret) | Verify inbound webhook signature |

Errors

• KeverdError — validation / network / timeout
• KeverdAPIError — non-2xx from the API (statusCode, body)
• KeverdSignatureError — bad webhook signature

License

MIT