Fastify

Guard Fastify routes with the traceHook pre-handler.

5 minutes

This quickstart verifies Trace events in a Fastify app with the traceHook pre-handler from @trace-id/sdk-node.

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
    .env
    TRACE_SECRET_KEY=sk_...
    TRACE_ENDPOINT=https://id.example.com
  2. 2

    Guard a route

    The hook reads the event id from the x-trace-event-id header or the parsed body, verifies it, and sets request.trace to the server-verified event.

    TypeScript
    import Fastify from 'fastify';
    import { traceHook } from '@trace-id/sdk-node/fastify';
    
    const app = Fastify();
    
    app.post(
      '/api/signup',
      { preHandler: traceHook({ failOpen: true, reject: (event) => event.suspectScore >= 60 }) },
      async (request) => {
        const event = request.trace; // null only with failOpen when Trace was unreachable
        // create the account, and store event?.visitorId with it for later lookups
        return { ok: true };
      },
    );

    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.

    To guard every route in a plugin, register it as a hook: app.addHook('preHandler', traceHook()). For TypeScript, declare the property:

    TypeScript
    import type { EventResponse } from '@trace-id/signals/api';
    
    declare module 'fastify' {
      interface FastifyRequest {
        trace?: EventResponse | null;
      }
    }

    Running Trace's own engine inside Fastify? See embedded mode.

    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.