SJWT SDK (Node.js / TypeScript)

Secure JWT (SJWT) SDK for Node.js and TypeScript applications. This SDK provides a simple, type-safe interface for generating, verifying, and rotating JWT tokens, with built-in protection against common vulnerabilities like replay attacks and token theft.

Features

• Token Lifecycle Management: Generate, verify, and rotate JWT tokens with ease.
• Security Features:
  • Fingerprint Protection: Tokens are tied to a unique fingerprint of the device/browser.
  • IP Binding: Tokens are validated against the IP address from which they were issued.
  • User-Agent Binding: Tokens are validated against the User-Agent string.
  • Revocation: Instant token revocation with real-time statistics.
• Express Middleware: Seamless integration with Express.js applications.
• TypeScript Support: Fully typed with TypeScript interfaces and JSDoc.

Installation

npm install @sjwt/sdk
# or
yarn add @sjwt/sdk

Configuration

You must configure the SDK using environment variables from your dashboard before initiating the client.

| Environment Variable | Description | Default | |----------------------|-------------|---------| | SJWT_PROJECT_ID | Your project ID | (Required) | | SJWT_SIGNATURE_KEY | Your signature key | (Required) |

Usage

1. Initialization

Initialize the SDK by invoking new SJWT(). The constructor automatically triggers an initialization check binding your project context.

import { SJWT } from "@sjwt/sdk";

// Dependencies loaded from process.env automatically
const sjwt = new SJWT();

2. Generating a Token

Generate a new token with optional payload and TTL. Pass the raw Node/Express incoming request (req), and the SDK will automatically extract network fields and build a secure digital fingerprint.

app.post("/login", async (req, res) => {
  const options: SignOptions = {
    payload: { userId: "user-123", role: "admin" },
    ttlSeconds: 3600, // 1 hour
    type: "ACCESS", // ACCESS, REFRESH
    req // Pass the Express or Node.js request object directly
  };

  const token = await sjwt.sign(options);
  res.json({ token });
});

3. Verifying a Token

Verify a token manually by providing the raw request. The SDK extracts IP, User-Agent, and Accept-Language for verification automatically.

app.get("/verify", async (req, res) => {
  const result = await sjwt.verify({
    token: "your-token",
    req // The incoming Express/Node request
  });

  if (result.valid) {
    console.log("Token is valid. Claims:", result.claims);
  } else {
    console.log("Token is invalid. Error:", result.errorCode);
  }
});

if (!result.valid) {
  switch (result.errorCode) {
    case "DEVICE_MISMATCH":  // stolen token
    case "THREAT_DETECTED":  // anomaly flagged
    case "REVOKED":          // already revoked
  }
}

4. Rotating a Refresh Token

Rotate an existing refresh token to generate a new one, optionally with an updated payload and TTL.

app.post("/refresh", async (req, res) => {
  const rotatedToken = await sjwt.rotate({
    oldToken: "your-old-refresh-token",
    payload: { userId: "user-123", role: "admin" },
    ttlSeconds: 3600,
    req // Pass the incomng request for verification and re-fingerprinting
  });

  console.log("Rotated Token:", rotatedToken);
});

5. Revoking a Token

Revoke a token immediately.

await sjwt.revoke("your-token", "ACCESS");
console.log("Token revoked.");

6. Express Middleware

Integrate the verification layer across routes seamlessly with the SJWT Express middleware.

import express from "express";
import { SJWT, sjwtMiddleware } from "@sjwt/sdk";

const app = express();
const sjwt = new SJWT();

app.use(express.json());

// Apply globally or on select routes
app.use(sjwtMiddleware(sjwt));

// Protected route
app.get("/api/protected", (req, res) => {
  // If the request makes it here, verification succeeded.
  // req.sjwt is populated by the middleware containing extracted claims.
  res.json({ message: "Access granted", claims: req.sjwt?.claims });
});

app.listen(3000, () => console.log("Server running on port 3000"));

Security Considerations

• Reverse Proxies: The SDK extracts the IP using the standard X-Forwarded-For HTTP header, then falls back to req.socket.remoteAddress. If you are running behind a reverse proxy (Nginx, ALB, Cloudflare, etc.), ensure Express is configured to trust the proxy (e.g. app.set('trust proxy', true)).
• Fingerprint: The SDK computes a deterministic fingerprint utilizing browser standards sent in headers (User-Agent and Accept-Language).
• Token Rotation: Rotate refresh tokens to avoid a potential compromise.
• Revocation: The global SJWT threat detection handles instant revocation and blocks blacklisted tokens via a centralized cuckoo filter implementation. Use the revoke functionality immediately when a token acts suspiciously or logout.

License

ISC