This quickstart verifies Trace events in a Hono app with guardRequest from @trace-id/sdk-node. It works on Node.js, Bun, Deno and Cloudflare Workers because it only uses the standard Request and Response.
Before you start
You need a secret key (sk_...) from the dashboard's Keys page and a frontend that sends an eventId (see the Web quickstarts). Send it in the x-trace-event-id header or as eventId in the request body.
- 1
Install the SDK
npm install @trace-id/sdk-nodepnpm add @trace-id/sdk-nodebun add @trace-id/sdk-nodeOn Workers, set
TRACE_SECRET_KEYandTRACE_ENDPOINTas secrets and pass them as options (shown below), since the guard cannot readprocess.envthere. - 2
Add a middleware
TypeScriptimport { Hono } from 'hono'; import { createMiddleware } from 'hono/factory'; import { guardRequest } from '@trace-id/sdk-node/web'; import type { EventResponse } from '@trace-id/signals/api'; type Env = { Bindings: { TRACE_SECRET_KEY: string; TRACE_ENDPOINT: string }; Variables: { trace: EventResponse | null }; }; const trace = createMiddleware<Env>(async (c, next) => { const guard = await guardRequest(c.req.raw, { secretKey: c.env.TRACE_SECRET_KEY, endpoint: c.env.TRACE_ENDPOINT, failOpen: true, reject: (event) => event.suspectScore >= 60, }); if (guard.response) return guard.response; // 400, 403, 503 or 500, with a JSON error body c.set('trace', guard.event); await next(); }); const app = new Hono<Env>(); app.post('/api/signup', trace, async (c) => { const { email } = await c.req.json(); // the body is still readable const event = c.get('trace'); // null only with failOpen when Trace was unreachable // create the account, and store event?.visitorId with it for later lookups return c.json({ ok: true }); }); export default app;The guard reads the event id from the
x-trace-event-idheader, a JSON body or a form body. The guard answers 400 for a missing or invalid event, 403 whenrejectsays so, 503 when Trace cannot be reached and 500 for a bad key or missing configuration.failOpen: truelets requests through (with the eventnull) when Trace is unreachable. A wrong key never fails open.Start in shadow mode
For the first week, log
event.suspectScoreandevent.reasonsinstead of rejecting. Look at who would have been blocked, then pick thresholds you trust.