This quickstart verifies Trace events in a NestJS app. A small guard calls verifyEvent from @trace-id/sdk-node, so it works with both the Express and Fastify platforms.
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-nodeyarn add @trace-id/sdk-node.envTRACE_SECRET_KEY=sk_... TRACE_ENDPOINT=https://id.example.com - 2
Write the guard
TypeScript// trace.guard.ts import { BadRequestException, CanActivate, ExecutionContext, ForbiddenException, Injectable, ServiceUnavailableException, } from '@nestjs/common'; import { verifyEvent } from '@trace-id/sdk-node'; import { VerifyError } from '@trace-id/sdk-node/errors'; @Injectable() export class TraceGuard implements CanActivate { async canActivate(context: ExecutionContext): Promise<boolean> { const req = context.switchToHttp().getRequest(); const eventId: string | undefined = req.headers['x-trace-event-id'] ?? req.body?.eventId; if (!eventId) throw new BadRequestException('Missing Trace event id'); try { const event = await verifyEvent(eventId, { secretKey: process.env.TRACE_SECRET_KEY!, endpoint: process.env.TRACE_ENDPOINT!, timeoutMs: 1500, }); if (event.suspectScore >= 60) throw new ForbiddenException('Request rejected'); req.trace = event; // the server-verified event return true; } catch (err) { if (!(err instanceof VerifyError)) throw err; if (err.code === 'unauthorized') throw err; // a wrong key is our bug: never fail open if (['not_found', 'expired', 'invalid_event_id'].includes(err.code)) throw new BadRequestException('Invalid Trace event'); throw new ServiceUnavailableException('Trace could not verify the event'); // or return true to fail open } } } - 3
Use it
TypeScript// signup.controller.ts import { Body, Controller, Post, Req, UseGuards } from '@nestjs/common'; import { TraceGuard } from './trace.guard'; @Controller('signup') export class SignupController { @Post() @UseGuards(TraceGuard) create(@Body() body: { email: string }, @Req() req: { trace: { visitorId: string } }) { // create the account, and store req.trace.visitorId with it for later lookups return { ok: true }; } }On the Express platform you can also use the ready-made middleware:
consumer.apply(traceGuard({ failOpen: true })).forRoutes('signup')withtraceGuardfrom@trace-id/sdk-node/express. On the Fastify platform,traceHookfrom@trace-id/sdk-node/fastifyfitsaddHook('preHandler', ...).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.