@socketfi/server

Server-side SDK for verifying SocketFi authentication tokens.

Install

npm install @socketfi/server

Requirements

• Node.js 18+

Usage

ES Modules

import express from "express";
import { SocketFi } from "@socketfi/server";

const app = express();

app.use(express.json());

const socketfi = new SocketFi({
  clientId: process.env.APP_CLIENT_ID!,
  secretKey: process.env.APP_SECRET_KEY!,
});

app.post("/api/auth/verify", async (req, res) => {
  try {
    const authHeader = req.headers.authorization;

    if (!authHeader?.startsWith("Bearer ")) {
      return res.status(401).json({
        success: false,
        error: "Authorization header missing",
      });
    }

    const token = authHeader.split(" ")[1];

    const session = await socketfi.verifyAuth(token);

    return res.json({
      success: true,
      user: {
        userId: session.userId,
        username: session.username,
        wallet: session.wallet,
      },
    });
  } catch (error) {
    return res.status(401).json({
      success: false,
      error: error instanceof Error ? error.message : "Invalid SocketFi token",
    });
  }
});

CommonJS

const { SocketFi } = require("@socketfi/server");

Environment variables

APP_CLIENT_ID=project_xxx
APP_SECRET_KEY=sk_live_xxx

secretKey must only be used on trusted backend servers. Never expose it in browsers, mobile apps, or client-side code.

Verification model

SocketFi access tokens are signed using RS256 asymmetric cryptography.

The SDK validates:

• Token signature
• Token expiration
• Issuer
• Audience (clientId)
• Token type (access)
• Signing algorithm

Verification flow:

• SocketFi private keys sign tokens.

• SocketFi public keys verify tokens.

• Your project's secretKey authenticates requests to the SocketFi key service.

• Public keys are cached in memory for improved performance.

• The SDK automatically refreshes public keys when:

  • the cache expires
  • token verification fails due to signature mismatch
  • a JWT kid mismatch is detected

Supported runtimes

• Node.js
• Express
• Next.js API routes
• NestJS
• Fastify
• Serverless functions

Edge runtimes are not currently supported.

Config

const socketfi = new SocketFi({
  clientId: "project_xxx",
  secretKey: "sk_live_xxx",
});

API

verifyAuth(token)

Verifies a SocketFi-issued access token and returns the authenticated session payload.

const session = await socketfi.verifyAuth(token);

Returned payload:

{
  userId: string;
  accountId?: string;
  username?: string;
  wallet?: SocketFiWallet;
  clientId: string;
  origin: string;
  expiresAt?: Date;
  accessToken: string;
  raw: SocketFiAccessTokenPayload;
}

verifyAuth() throws if:

• the token is invalid
• the token is expired
• the token audience does not match your clientId
• the token signature verification fails
• the token type is invalid

clearKeyCache()

Clears the in-memory SocketFi public key cache.

socketfi.clearKeyCache();

Stability

This SDK follows semantic versioning.

Breaking API changes are introduced only in major releases.

License

Apache-2.0