SocketFi Auth Middleware — Express, Fastify, NestJS

Rather than calling verifyAuth() directly inside every route handler, the recommended pattern is to extract the verification logic into reusable middleware. This keeps your route handlers focused on business logic and ensures that no protected route accidentally skips token verification. The examples below show how to build auth middleware for Express, Fastify, and NestJS, including how to attach the verified user and wallet to the request object so downstream handlers can use them without re-verifying.

TypeScript: extending the request type

Before writing middleware, extend the framework’s request type so TypeScript knows about the auth property your middleware attaches:

// src/types/express.d.ts
import { VerifyAuthResult } from '@socketfi/server';

declare global {
  namespace Express {
    interface Request {
      auth?: VerifyAuthResult & { valid: true };
    }
  }
}

This gives you full type-safety when accessing req.auth.user.id or req.auth.wallet.address inside route handlers.

Express middleware

The following authMiddleware function reads the token from the Authorization header, calls verifyAuth(), and either attaches the result to req.auth and calls next(), or responds immediately with a 401:

import { Request, Response, NextFunction } from 'express';
import { verifyAuth } from '@socketfi/server';

export async function authMiddleware(
  req: Request,
  res: Response,
  next: NextFunction
): Promise<void> {
  const token = req.headers.authorization?.replace('Bearer ', '');

  if (!token) {
    res.status(401).json({ error: 'Unauthorized' });
    return;
  }

  const auth = await verifyAuth(token);

  if (!auth.valid) {
    res.status(401).json({ error: auth.error.code });
    return;
  }

  // Attach verified identity to the request for downstream handlers
  req.auth = auth;
  next();
}

Protected Express routes

Apply authMiddleware to any route that requires authentication:

import express from 'express';
import { authMiddleware } from './middleware/auth';

const app = express();

// Single protected route
app.get('/profile', authMiddleware, async (req, res) => {
  res.json({
    userId: req.auth!.user.id,
    walletAddress: req.auth!.wallet.address,
  });
});

// Apply middleware to all routes under /api
const api = express.Router();
api.use(authMiddleware);

api.get('/balance', async (req, res) => {
  const { address } = req.auth!.wallet;
  const balance = await fetchBalance(address);
  res.json({ balance });
});

api.post('/transfer', async (req, res) => {
  const { id: userId } = req.auth!.user;
  // ... handle transfer
});

app.use('/api', api);

Fastify preHandler

In Fastify, use a preHandler hook to run verification before each request reaches its handler. You can register it globally or on a specific route:

import Fastify from 'fastify';
import { verifyAuth } from '@socketfi/server';

const fastify = Fastify();

// Augment Fastify's request type
declare module 'fastify' {
  interface FastifyRequest {
    auth?: Awaited<ReturnType<typeof verifyAuth>> & { valid: true };
  }
}

// Global preHandler — runs on every registered route
fastify.addHook('preHandler', async (request, reply) => {
  const token = request.headers.authorization?.replace('Bearer ', '');

  if (!token) {
    return reply.status(401).send({ error: 'Unauthorized' });
  }

  const auth = await verifyAuth(token);

  if (!auth.valid) {
    return reply.status(401).send({ error: auth.error.code });
  }

  request.auth = auth;
});

Protected Fastify routes

fastify.get('/profile', async (request, reply) => {
  return {
    userId: request.auth!.user.id,
    walletAddress: request.auth!.wallet.address,
  };
});

fastify.post('/transfer', async (request, reply) => {
  const { id: userId } = request.auth!.user;
  // ... handle transfer
  return { success: true };
});

If you only want to protect specific routes rather than every route, register the preHandler at the route level instead of with addHook: fastify.get('/protected', { preHandler: authPreHandler }, handler).

NestJS Guard

In NestJS, implement authentication as a Guard that uses CanActivate. The guard runs before the route handler and throws UnauthorizedException if the token is invalid:

// src/auth/socketfi.guard.ts
import {
  Injectable,
  CanActivate,
  ExecutionContext,
  UnauthorizedException,
} from '@nestjs/common';
import { verifyAuth } from '@socketfi/server';

@Injectable()
export class SocketFiGuard implements CanActivate {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = request.headers.authorization?.replace('Bearer ', '');

    if (!token) {
      throw new UnauthorizedException('Missing token');
    }

    const auth = await verifyAuth(token);

    if (!auth.valid) {
      throw new UnauthorizedException(auth.error.code);
    }

    // Attach verified identity so controllers can access it
    request.auth = auth;
    return true;
  }
}

Protected NestJS routes

Apply SocketFiGuard with the @UseGuards() decorator at the controller or method level:

// src/profile/profile.controller.ts
import { Controller, Get, Req, UseGuards } from '@nestjs/common';
import { SocketFiGuard } from '../auth/socketfi.guard';
import { Request } from 'express';

@Controller('profile')
@UseGuards(SocketFiGuard) // Protects all routes in this controller
export class ProfileController {
  @Get()
  getProfile(@Req() req: Request) {
    return {
      userId: req['auth'].user.id,
      walletAddress: req['auth'].wallet.address,
    };
  }
}

To protect all routes in your entire application, register SocketFiGuard as a global guard in your AppModule:

// src/app.module.ts
import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { SocketFiGuard } from './auth/socketfi.guard';

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: SocketFiGuard,
    },
  ],
})
export class AppModule {}

Accessing user and wallet info in handlers

Regardless of framework, once middleware attaches the auth object to the request, your handlers can read the verified identity without any additional SDK calls:

// Available after middleware runs:
const userId        = req.auth.user.id;        // e.g. "usr_01hx..."
const walletAddress = req.auth.wallet.address; // e.g. "GDZX..."

// Common pattern — look up the user in your own database
const account = await db.accounts.findOne({ socketfiId: userId });

Never skip the middleware on routes that access user data or perform wallet operations. A missing Authorization header is not the same as an unauthenticated user — always handle the !token case explicitly and return a 401 before calling verifyAuth().

React SDK

React Native SDK

Server SDK

API Reference

SocketFi Auth Middleware — Express, Fastify, NestJS

TypeScript: extending the request type

Express middleware

Protected Express routes

Fastify preHandler

Protected Fastify routes

NestJS Guard

Protected NestJS routes

Accessing user and wallet info in handlers

​TypeScript: extending the request type

​Express middleware

​Protected Express routes

​Fastify preHandler

​Protected Fastify routes

​NestJS Guard

​Protected NestJS routes

​Accessing user and wallet info in handlers

TypeScript: extending the request type

Express middleware

Protected Express routes

Fastify preHandler

Protected Fastify routes

NestJS Guard

Protected NestJS routes

Accessing user and wallet info in handlers