Hono

Guard Hono routes on Node, Bun, Deno and Workers.

5 minutes

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. 1

    Install the SDK

    npm install @trace-id/sdk-node

    On Workers, set TRACE_SECRET_KEY and TRACE_ENDPOINT as secrets and pass them as options (shown below), since the guard cannot read process.env there.

  2. 2

    Add a middleware

    TypeScript
    import { 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-id header, a JSON body or a form body. The guard answers 400 for a missing or invalid event, 403 when reject says so, 503 when Trace cannot be reached and 500 for a bad key or missing configuration. failOpen: true lets requests through (with the event null) when Trace is unreachable. A wrong key never fails open.

    Start in shadow mode

    For the first week, log event.suspectScore and event.reasons instead of rejecting. Look at who would have been blocked, then pick thresholds you trust.

Frontends

Next steps

Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.