DEV Community: Wesley Israel

The Secret Weapon Every Developer Needs: Cursor + Figma MCP Integration

Wesley Israel — Mon, 04 Aug 2025 17:01:43 +0000

The Secret Weapon Every Developer Needs: Cursor + Figma MCP Integration

Listen up, developers! If you're still manually copying design tokens from Figma or screenshotting components like it's 2010, you're doing it wrong. There's a better way, and it's called MCP (Message Communication Protocol).

Yeah, it's that cool.

What the Heck is MCP?

MCP is like having a direct hotline between your editor and Figma. No more context switching, no more copy-paste madness, no more "where did I put that color code again?" moments.

Think of it as your personal Figma assistant that lives right inside Cursor. Mind-blowing, right?

The Setup That Will Change Your Life

Step 1: Configure Your MCP Settings

Open your Cursor settings and add this configuration to your MCP setup:

{
  "mcpServers": {
    "Framelink Figma MCP Personal": {
      "command": "npx",
      "args": [
        "-y",
        "figma-developer-mcp",
        "--figma-api-key=YOUR_API_KEY_HERE",
        "--stdio"
      ]
    }
  }
}

Pro tip: Replace YOUR_API_KEY_HERE with your actual Figma API key. You can get one from your Figma account settings.

Step 2: Get Your Figma API Key

Go to your Figma account settings
Navigate to Personal access tokens
Create a new token
Copy that bad boy and paste it in the config above

Step 3: Restart Cursor and Start Using

Restart Cursor, and you're ready to go! No installation needed — just copy a Figma frame link and paste it in the chat to get all the data you need.

What You Can Do Now (That You Couldn't Before)

Extract design tokens directly from Figma components
Get component information without leaving your editor
Download images and SVGs with a simple command
Access layout data for responsive design implementation
Sync color palettes automatically

Real-World Example: The Magic of Frame Links

Here's how you'd extract data from your Figma file:

// Before MCP (the dark ages)
// 1. Open Figma
// 2. Find the component
// 3. Copy the hex code
// 4. Paste in your code
// 5. Repeat 50 times

// After MCP (the enlightened era)
// Just paste a Figma frame link in the chat:
// https://www.figma.com/file/abc123/MyDesign?node-id=123:456
// Boom! All your design data in one go

The Benefits That Will Make Your Teammates Jealous

✅ Zero context switching — Stay in your flow
✅ Real-time design sync — Always up-to-date
✅ Automated token extraction — No more manual work
✅ Version control for design — Track design changes
✅ Faster development cycles — Ship features faster

Common Gotchas (Don't Say I Didn't Warn You)

API Rate Limits: Figma has rate limits, so don't go crazy with requests
File Permissions: Make sure you have access to the Figma files you're trying to connect
Token Security: Keep your API key secure and never commit it to version control

The Call to Action That Will Change Your Development Life

Ready to join the future of design-to-code workflow?

Configure your MCP settings (it takes 2 minutes)
Copy a Figma frame link and paste it in the chat
Watch the magic happen as all your design data appears
Share this article with your team (they'll thank you)

Your future self will thank you for reading this far. Now go forth and build amazing things with the power of Cursor + Figma MCP!

P.S. If you're still manually copying design tokens, you're literally living in the past. Time to upgrade your workflow! 🚀

Real‑World Applications of AI: Lessons from Successful Projects

Wesley Israel — Fri, 01 Aug 2025 23:50:47 +0000

Real‑World Applications of AI: Lessons from Successful Projects

Artificial intelligence is no longer an exotic research topic—it is a core part of modern products and services. From recommendation engines to generative assistants, AI is solving real business problems, but success is not guaranteed. Many early attempts fail because teams focus on the model instead of the end‑to‑end solution or because projects are driven by hype rather than measurable outcomes. This article distills lessons from real‑world AI deployments across industries and outlines practices for experienced developers and tech leads who want to deliver sustainable value.

Why AI projects succeed or fail

AI projects differ from traditional software projects. Models are only as good as the data they are trained on and the surrounding infrastructure. Michelle K. Lee, former director of the U.S. Patent and Trademark Office and now VP of machine learning at Amazon Web Services, notes that successful machine‑learning solutions start with a strong data strategy—treating data as an organizational asset, democratizing access, ensuring compliance and putting it to work through analytics【138012276578581†L169-L193】. Without accessible, high‑quality data, teams spend their time cleaning and wrangling rather than building models【138012276578581†L174-L182】.

Selecting the right use cases is equally important. Lee advises businesses to start by identifying high‑impact problems that have sufficient data and are amenable to machine learning【138012276578581†L204-L214】. A high‑impact problem without data will frustrate data scientists, while a well‑supported use case with low business impact will fail to gain adoption【138012276578581†L206-L213】. In short, not every problem is solvable by AI; tech leads must weigh data readiness, business value and ML applicability【138012276578581†L215-L217】.

Seven lessons from successful machine‑learning projects

The MIT Sloan article “7 lessons to ensure successful machine learning projects” summarises insights from real deployments【138012276578581†L169-L193】. Key takeaways for practitioners:

Invest in data strategy – treat data as an organizational asset, democratize access and build pipelines that support analytics and machine learning【138012276578581†L169-L193】.
Choose use cases wisely – align projects with business goals, assess data availability, model feasibility and define clear success metrics【138012276578581†L204-L214】.
Build cross‑functional teams – combine technical experts with domain experts to close cultural gaps and ensure adoption【138012276578581†L228-L235】.
Secure executive sponsorship and foster experimentation – projects need top‑level support and a culture that tolerates initial under‑performance and treats failures as learning opportunities【138012276578581†L237-L249】.
Address skills gaps – train existing staff and provide resources for both engineers and business leaders to understand ML【138012276578581†L252-L258】.
Invest in infrastructure and tools – avoid reinventing the wheel; use managed services and platforms to free teams from undifferentiated heavy lifting【138012276578581†L269-L281】.
Plan for the long term – machine‑learning models need continuous retraining and maintenance; start with small projects, demonstrate value and iterate【138012276578581†L283-L295】.

These lessons apply across industries and are particularly relevant for teams building AI features into large codebases. They emphasize organisational readiness (data and culture) and the importance of small, measurable wins.

Hard truths from the early days of generative AI

Generative AI has exploded in popularity, but many organisations are still experimenting. A McKinsey survey found that while 65 % of respondents were using generative AI, only 10 % had scaled it successfully【249839388272364†L165-L161】. At the MIT Sloan CIO Symposium, Aamer Baig highlighted seven “hard truths” for generative‑AI adoption【249839388272364†L165-L181】:

Not all use cases are equal – generative AI initiatives are often scattershot and don’t improve the bottom line; prioritise high‑value, feasible and low‑risk use cases【249839388272364†L169-L181】.
It’s about the stack, not just the model – enterprise‑scale AI requires 20–30 components such as large language models, data gateways, prompt engineering, security and orchestration【249839388272364†L183-L190】. Teams must integrate the entire stack rather than focusing only on the model.
Manage costs carefully – change management can cost up to three times the technology itself; generative‑AI maintenance may equal development costs【249839388272364†L200-L218】. Budget accordingly and make informed platform choices.
Tame tool proliferation – standardise tools to avoid fragmentation and maintain team productivity【249839388272364†L224-L229】.
Assemble product‑oriented teams – organise work around integrated, cross‑functional pods with visibility from top management【249839388272364†L231-L239】.
Get the right data, not perfect data – focus on data domains that can be reused across multiple use cases; perfection is not required to start【249839388272364†L249-L254】.
Reuse models, prompts and patterns – develop reuse strategies for AI assets to accelerate delivery and sustain impact【249839388272364†L256-L262】.

These principles mirror the earlier lessons: start small, integrate the stack, manage costs and focus on reusable infrastructure.

Case studies: small‑scale transformations and industry examples

CarMax: CarMax uses generative AI to summarise thousands of customer reviews so that shoppers can quickly compare vehicles【371789606176673†L164-L190】. By targeting a specific, high‑impact task (content summarisation), CarMax achieved measurable value without overhauling its entire tech stack【371789606176673†L195-L199】. This demonstrates the benefit of starting with well‑scoped use cases.

E‑commerce chatbots: Many retailers deploy chatbots built on large language models to deliver personalised shopping experiences and support. MIT Sloan notes that companies such as Adobe and Canva embed generative AI tools directly into their products, enabling users to generate designs or content【371789606176673†L187-L190】. These features are integrated into existing workflows rather than replacing them.

Colgate‑Palmolive: The consumer goods firm applies retrieval‑augmented generation to its vast trove of proprietary research and third‑party data【371789606176673†L206-L218】. Employees can query this data using natural language and receive synthesized insights, speeding up market research. Colgate also uses generative AI to develop and test new product concepts with digital consumer twins, enabling rapid iteration and reducing the need for physical focus groups【371789606176673†L221-L226】. Access to the company’s AI hub requires training in responsible use, and thousands of employees report improved creativity【371789606176673†L228-L233】. This case underscores the value of combining domain expertise with AI and investing in governance and education.

Liberty Mutual and Sanofi: These companies use intelligent choice architectures that combine predictive and generative AI to generate sets of options and explain trade‑offs【371789606176673†L237-L256】. Liberty Mutual helps claims adjusters triage calls, while Sanofi uses AI to optimise investment decisions and overcome sunk‑cost bias【371789606176673†L248-L252】. Such systems shift decision rights from individuals to the environment, raising governance questions about accountability and oversight【371789606176673†L254-L263】.

These case studies illustrate that successful AI applications often start with narrowly defined, high‑value tasks and expand gradually. They also highlight the importance of human oversight, data governance and employee training.

Lessons for developers and tech leads

For engineers building AI‑powered features, the following guidelines can help turn theory into practice:

Start with a concrete problem and success metrics. Identify pain points where AI can deliver quantifiable improvements (e.g., reducing support response times or increasing conversion rates). Define how you will measure success and align with business stakeholders.
Prioritise data quality and accessibility. Work with data engineers to ensure that the necessary data is available, clean and ethically sourced. Document data lineage and include bias checks【138012276578581†L169-L193】.
Design for privacy and security. Consider how sensitive information flows through your models, apply differential privacy where appropriate and adhere to regulations such as GDPR or Brazil’s LGPD. Use retrieval‑augmented generation or prompt sanitization to prevent leaking confidential data.
Choose the right architecture. For classical ML tasks, you might deploy models behind REST or gRPC APIs; for generative AI features, you may need to orchestrate multiple services—LLMs, embedding databases, vector stores and caching layers【249839388272364†L183-L190】. Build modular services that you can swap out as models evolve.
Invest in MLOps and monitoring. Automate model training, deployment and rollback. Monitor accuracy, latency and drift; plan for retraining and iterative improvement【138012276578581†L283-L295】.
Implement responsible AI practices. Build fairness and explainability into your pipeline. Document model limitations and include human‑in‑the‑loop mechanisms for high‑impact decisions. Train team members on responsible use, as Colgate‑Palmolive does with its AI hub【371789606176673†L228-L233】.
Iterate and scale gradually. Start with a pilot, validate value, then integrate AI deeper into your stack. Reuse models, prompts and infrastructure to accelerate subsequent projects【249839388272364†L256-L262】.

Summary

Real‑world AI success is less about the sophistication of the model and more about data readiness, problem selection, team collaboration and governance. Lessons from MIT Sloan highlight the need for a strong data strategy, carefully chosen use cases, cross‑functional teams and long‑term thinking【138012276578581†L169-L193】【138012276578581†L204-L214】. Generative AI adds additional challenges: integrating an entire tech stack, managing costs and ensuring reuse【249839388272364†L183-L190】【249839388272364†L200-L218】. Case studies from CarMax, Colgate‑Palmolive, Liberty Mutual and Sanofi demonstrate that starting with targeted, high‑value applications and investing in training and governance leads to measurable outcomes【371789606176673†L164-L190】【371789606176673†L206-L233】. By applying these lessons, experienced developers and tech leads can build AI solutions that deliver real value while minimizing risk.

How to Create Two‑Factor Authentication (2FA) and Best Practices

Wesley Israel — Fri, 01 Aug 2025 23:24:28 +0000

Two‑factor authentication (2FA) is no longer optional for modern web and mobile applications. Passwords are easy to guess, steal or reuse, and API endpoints are under constant attack (some sources estimate over 90 k attacks on APIs per minute[1]). By adding a second factor—such as a time‑based one‑time password (TOTP), hardware token or passkey—you drastically reduce the risk of credential stuffing, phishing, session hijacking and other common threats. In this article you will learn why 2FA matters, how to implement it in a Node.js/TypeScript backend and integrate it with React/Next.js, and what security practices you should follow to avoid common pitfalls.

Why 2FA matters

Two‑factor authentication is a specific type of multi‑factor authentication requiring two distinct forms of identification[1]. The most common combination is “something you know” (password or PIN) and “something you have” (smartphone running an authenticator app). 2FA mitigates several attack vectors:

Credential theft and replay attacks – Even if a password is compromised, an attacker cannot log in without the second factor.
Phishing and social engineering – OTPs expire quickly and cannot be reused.
Brute‑force and credential stuffing – Rate‑limiting on OTP verification makes automated attacks impractical[3].

2FA is also simple and cost‑effective for end users. Most authenticator apps (Google Authenticator, Authy, Microsoft Authenticator) are free and widely available, and scanning a QR code is easier than typing complex passwords[1].

Recommended 2FA strategies

The OWASP Multifactor Authentication cheat sheet outlines several high‑level recommendations suitable for most applications[2]:

Require some form of MFA for all users.
Provide users the option to enable MFA using TOTP.
Always enforce MFA for administrators or high‑privilege accounts.
Implement a secure MFA reset process (recovery codes, support workflow).
Consider third‑party MFA providers if you lack the resources to build and maintain your own implementation.

Teleport’s Authentication Best Practices add further hardening guidelines[3]:

Prefer passwordless or hardware‑token (U2F) based 2FA over TOTP or SMS.
Ensure authenticated sessions are created only after successful 2FA verification.
Require re‑authentication to change 2FA settings.
Apply rate‑limiting to failed 2FA attempts.

These recommendations should drive your design regardless of the framework or language you use.

Implementing TOTP 2FA in Node.js / TypeScript

Choosing a library

Historically many tutorials used the speakeasy library to generate and verify TOTPs. However, speakeasy has not been updated in several years, prompting many developers to switch to more actively maintained alternatives. The codevoweb tutorial notes that speakeasy’s maintenance gap is a common pain point and recommends using the otpauth library instead[1].

We will use the otpauth package for generating secrets and verifying tokens. You will also need qrcode to render the QR code used by the authenticator app.

npm install otpauth qrcode

Generating a TOTP secret and QR code

Create a helper module 2fa.ts that handles generation and verification of TOTP secrets. The example uses TypeScript and assumes you store the secret in your database associated with the user record (ideally encrypted at rest):

// src/utils/twoFactor.ts
import { TOTP } from 'otpauth';
import QRCode from 'qrcode';

export interface TwoFactorSecret {
  secret: string;            // base32 encoded secret
  otpauthUrl: string;        // URI for authenticator apps
  qrCodeDataUrl: string;     // data URL for QR code
}

/**
 * Generate a TOTP secret for a user and return the secret and QR code.
 */
export async function generateTwoFactorSecret(userEmail: string): Promise<TwoFactorSecret> {
  // The label becomes the account name shown in the authenticator app
  const totp = new TOTP({
    issuer: 'YourAppName',
    label: userEmail,
    algorithm: 'SHA1', // RFC 6238 default
    digits: 6,
    period: 30,
  });

  const secret = totp.secret.base32; // store this in DB (encrypted)
  const otpauthUrl = totp.toString();
  const qrCodeDataUrl = await QRCode.toDataURL(otpauthUrl);
  return { secret, otpauthUrl, qrCodeDataUrl };
}

/**
 * Verify a user‑supplied TOTP token.
 */
export function verifyTwoFactorToken(token: string, secret: string): boolean {
  const totp = new TOTP({ secret });
  // Use the built‑in check; allows slight clock drift and returns the matching delta
  const delta = totp.validate({ token, window: 1 });
  return delta !== null;
}

The generateTwoFactorSecret function constructs a new TOTP with an issuer (your application name) and label (the user’s email) and returns a Base32 secret and a QR code. The verifyTwoFactorToken function validates a 6‑digit token using the secret stored in your database and allows a small time window (window: 1) to account for clock drift.

Express route handlers

Create a set of endpoints to enable, verify and disable 2FA for a user. These handlers assume you have user authentication and session management in place using JWT or session cookies. The 2FA state is stored on the user model (twoFactorEnabled: boolean, twoFactorSecret: string | null).

// src/routes/twoFactorRoutes.ts
import { Router, Request, Response } from 'express';
import { generateTwoFactorSecret, verifyTwoFactorToken } from '../utils/twoFactor';
import { prisma } from '../db';

const router = Router();

// Step 1: generate secret and send QR code
router.post('/generate', async (req: Request, res: Response) => {
  const userId = req.user.id; // assume user is authenticated
  const user = await prisma.user.findUnique({ where: { id: userId } });
  if (user?.twoFactorEnabled) {
    return res.status(400).json({ message: '2FA already enabled' });
  }
  const { secret, qrCodeDataUrl } = await generateTwoFactorSecret(user.email);
  // Save secret (hashed or encrypted) but don’t mark 2FA as enabled yet
  await prisma.user.update({ where: { id: userId }, data: { twoFactorTempSecret: secret } });
  res.json({ qrCodeDataUrl });
});

// Step 2: verify token and enable 2FA
router.post('/verify', async (req: Request, res: Response) => {
  const { token } = req.body;
  const userId = req.user.id;
  const user = await prisma.user.findUnique({ where: { id: userId } });
  if (!user?.twoFactorTempSecret) {
    return res.status(400).json({ message: 'No 2FA setup in progress' });
  }
  const isValid = verifyTwoFactorToken(token, user.twoFactorTempSecret);
  if (!isValid) {
    return res.status(400).json({ message: 'Invalid token' });
  }
  // Move the secret to permanent field and mark as enabled
  await prisma.user.update({
    where: { id: userId },
    data: {
      twoFactorSecret: user.twoFactorTempSecret,
      twoFactorTempSecret: null,
      twoFactorEnabled: true,
    },
  });
  res.json({ message: '2FA enabled' });
});

// Step 3: validate 2FA token during login
router.post('/validate', async (req: Request, res: Response) => {
  const { token } = req.body;
  const userId = req.user.id;
  const user = await prisma.user.findUnique({ where: { id: userId } });
  if (!user?.twoFactorEnabled || !user.twoFactorSecret) {
    return res.status(400).json({ message: '2FA not enabled' });
  }
  const isValid = verifyTwoFactorToken(token, user.twoFactorSecret);
  if (!isValid) {
    // Optionally increment failed attempt counter and rate‑limit
    return res.status(400).json({ message: 'Invalid token' });
  }
  // Mark the session as 2FA‑verified
  req.session.twoFactorVerified = true;
  res.json({ message: '2FA validation successful' });
});

// Step 4: disable 2FA (require re‑authentication and 2FA)
router.post('/disable', async (req: Request, res: Response) => {
  const { token } = req.body;
  const userId = req.user.id;
  const user = await prisma.user.findUnique({ where: { id: userId } });
  if (!user?.twoFactorEnabled || !user.twoFactorSecret) {
    return res.status(400).json({ message: '2FA not enabled' });
  }
  // Verify token again before disabling
  const isValid = verifyTwoFactorToken(token, user.twoFactorSecret);
  if (!isValid) {
    return res.status(400).json({ message: 'Invalid token' });
  }
  await prisma.user.update({
    where: { id: userId },
    data: { twoFactorEnabled: false, twoFactorSecret: null },
  });
  res.json({ message: '2FA disabled' });
});

export default router;

Key security considerations

Never store TOTP secrets in plain text. Encrypt secrets at rest (e.g., with libsodium or AWS KMS) and hash them using HMAC if you only need to verify tokens but not regenerate the QR code.
Rate‑limit failed verification attempts to mitigate brute‑force attacks[3].
Mark the session as 2FA‑verified after successful token validation and require this flag before issuing a JWT or setting a session cookie[3].
Require password+2FA for sensitive operations (updating email, password, or disabling 2FA)[2].

Integrating 2FA into React / Next.js

For the frontend we will build a simple component to enable and verify 2FA. When the user clicks “Enable 2FA,” the client fetches the QR code from /generate. The user scans the code with an authenticator app and enters the current 6‑digit token to enable 2FA.

// components/TwoFactorSetup.tsx
import React, { useState } from 'react';
import Image from 'next/image';
import axios from 'axios';

export default function TwoFactorSetup() {
  const [qrCode, setQrCode] = useState<string | null>(null);
  const [token, setToken] = useState('');
  const [enabled, setEnabled] = useState(false);
  const handleGenerate = async () => {
    const res = await axios.post('/api/auth/otp/generate');
    setQrCode(res.data.qrCodeDataUrl);
  };
  const handleVerify = async () => {
    try {
      await axios.post('/api/auth/otp/verify', { token });
      setEnabled(true);
    } catch (err) {
      alert('Invalid token');
    }
  };
  return (
    <div>
      {!qrCode && !enabled && (
        <button onClick={handleGenerate}>Enable 2FA</button>
      )}
      {qrCode && !enabled && (
        <div>
          <p>Scan this QR code with your authenticator app:</p>
          <Image src={qrCode} alt="2FA QR code" width={150} height={150} />
          <input
            type="text"
            placeholder="Enter 6‑digit code"
            value={token}
            onChange={(e) => setToken(e.target.value)}
          />
          <button onClick={handleVerify}>Verify & Activate</button>
        </div>
      )}
      {enabled && <p>Two‑factor authentication is enabled on your account.</p>}
    </div>
  );
}

The server and client exchange JSON only; the actual secret never leaves the server. You should protect these endpoints behind your existing authentication middleware so that only authenticated users can enable or disable 2FA.

React Native considerations

For mobile apps built with React Native, you can either:

Delegate scanning to the OS by displaying the otpauth URL as a link. On iOS and Android, authenticator apps can intercept otpauth:// URIs and prompt the user to add the account.
Use a QR‑code scanner library such as react-native-camera or expo-barcode-scanner to scan the QR code and display a manual entry field for the 6‑digit token.

When handling 2FA on mobile, never embed the TOTP secret in the mobile code. Always fetch and verify tokens via your backend API.

Beyond TOTP: Passkeys and hardware tokens

TOTP is popular because it is easy to implement and broadly supported. However, modern security guidelines recommend passwordless or hardware‑based 2FA whenever possible[3]. Passkeys (FIDO2/WebAuthn) combine the security of possession factors with biometric or PIN verification and provide resistance to phishing[2]. You can integrate passkeys in web applications using the WebAuthn API (navigator.credentials.create and navigator.credentials.get) with server‑side libraries like @simplewebauthn/server.

Hardware tokens (U2F) provide similar benefits and can be registered as an additional factor. When designing a 2FA system, offer multiple factor types (TOTP, passkey, hardware token) and let users select their preferred method. For high‑privilege accounts, require at least one hardware token.

Common mistakes and anti‑patterns

Storing secrets insecurely – Never store TOTP secrets unhashed or unencrypted. Use an HSM or key management service (KMS) to protect secrets.
Relying on SMS or email for 2FA – SMS OTPs are susceptible to SIM swapping and phishing. Email OTPs can be intercepted. Prefer TOTP, passkeys or hardware tokens[3].
Missing rate‑limiting – Without rate limits, attackers can brute‑force 2FA tokens. Use algorithms like token bucket or leaky bucket to rate‑limit failed attempts[3].
No session flag for 2FA – You must track whether a user has completed 2FA. Failing to do so can allow bypassing the second factor by replaying a valid session cookie[3].
Out‑of‑band MFA reset – Don’t allow users to reset 2FA via email without verifying their identity. Provide recovery codes and require additional verification when resetting MFA[2].
Using unmaintained libraries – Choose actively maintained TOTP/FIDO2 libraries. The speakeasy library has not been updated for years[1], so prefer alternatives like otpauth or @simplewebauthn.
Prompting for 2FA too often – Excessive prompts frustrate users and lead them to disable MFA. Implement risk‑based authentication to require MFA only in high‑risk scenarios (new device, unusual location)[2].

Summary and next steps

Two‑factor authentication significantly enhances the security of your applications by requiring an additional proof of identity beyond passwords. Following OWASP’s recommendations—enforcing MFA for all users, providing TOTP for convenience, securing the MFA reset process and considering third‑party providers[2]—will put you on solid footing. When implementing 2FA in your Node.js/TypeScript backend, use reliable libraries like otpauth, secure secrets at rest, track 2FA state in the session and apply rate‑limiting. On the frontend, guide users through scanning a QR code and entering the OTP, and consider supporting passkeys and hardware tokens for a passwordless future[3].

With these practices you can ship a robust 2FA solution that protects both your users and your infrastructure. For further reading, explore the OWASP Multifactor Authentication cheat sheet, Teleport’s Authentication Best Practices, and libraries such as @simplewebauthn/server for passkey support.

References

[1] CodevoWeb – How to Implement Two‑factor Authentication (2FA) in Node.js. 2023. https://codevoweb.com/two-factor-authentication-2fa-in-nodejs/.

[2] OWASP Cheat Sheet Series – Multifactor Authentication Cheat Sheet. https://cheatsheetseries.owasp.org/cheatsheets/Multifactor_Authentication_Cheat_Sheet.html.

[3] Teleport – Authentication Best Practices (2022). https://goteleport.com/blog/authentication-best-practices/.

Implementing a Leaky Bucket Rate Limiting System in Node.js:

Wesley Israel — Fri, 18 Jul 2025 21:11:32 +0000

📋 Introduction

Recently, I faced a fascinating technical challenge: implementing a complete rate limiting system using the Leaky Bucket strategy in Node.js. The project involved creating an HTTP server with authentication, GraphQL for PIX queries, and a multi-tenant system with granular token control.

In this article, I'll share my complete implementation journey, from initial architecture to final testing, including all technical decisions and challenges faced.

🎯 The Challenge

The goal was to build a system that:

✅ Node.js HTTP server with Koa.js and TypeScript
✅ Multi-tenancy strategy (each user with their own bucket)
✅ Bearer Token authentication (JWT)
✅ GraphQL mutation for PIX query
✅ Leaky Bucket strategy for token control
✅ Complete tests with Jest
✅ Postman documentation
✅ Load testing with k6

🏗️ System Architecture

Project Structure

leaky-bucket/
├── src/
│   ├── middleware/          # Authentication and rate limiting middlewares
│   ├── services/           # Business logic (auth, leaky bucket, PIX)
│   ├── graphql/            # GraphQL schema and resolvers
│   ├── models/             # Data models
│   ├── utils/              # Utilities (JWT, logger, metrics)
│   └── server.ts           # Main server
├── tests/                  # Jest and load tests
├── docs/                   # Documentation and Postman
└── scripts/                # Automation scripts

Data Flow

Client → Auth Middleware → Leaky Bucket → GraphQL Resolver → PIX Service

🔧 Detailed Implementation

1. Initial Configuration

I started by configuring the environment with TypeScript and necessary dependencies:

{
  "dependencies": {
    "koa": "^2.14.2",
    "koa-router": "^12.0.0",
    "graphql": "^16.8.1",
    "apollo-server-koa": "^3.12.1",
    "jsonwebtoken": "^9.0.2",
    "bcryptjs": "^2.4.3"
  }
}

2. Multi-Tenancy Strategy

I implemented a system where each user has their own token bucket:

// src/models/user.ts
interface User {
  id: string;
  email: string;
  name: string;
  password: string;
  tokens: number;
  maxTokens: number;
  lastRefill: Date;
}

class UserRepository {
  private users: Map<string, User> = new Map();

  createUser(email: string, password: string, name: string): User {
    const user: User = {
      id: generateId(),
      email,
      name,
      password: hashPassword(password),
      tokens: 10, // Initial tokens
      maxTokens: 10,
      lastRefill: new Date(),
    };

    this.users.set(user.id, user);
    return user;
  }
}

3. JWT Authentication

The authentication middleware validates tokens and extracts user information:

// src/middleware/auth.ts
export const authMiddleware = async (ctx: Context, next: Next) => {
  const authHeader = ctx.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    throw new UnauthorizedError('Authentication token required');
  }

  const token = authHeader.substring(7);
  const decoded = jwt.verify(token, JWT_SECRET) as JWTPayload;

  ctx.state.user = decoded;
  await next();
};

4. Leaky Bucket Strategy

The Leaky Bucket implementation was the heart of the system:

// src/services/leakyBucketService.ts
export class LeakyBucketService {
  private readonly LEAK_RATE = 1; // tokens per second
  private readonly REFILL_INTERVAL = 1000; // 1 second

  async consumeToken(userId: string): Promise<boolean> {
    const user = await this.userRepository.findById(userId);
    if (!user) throw new Error('User not found');

    // Calculate leaked tokens since last refill
    const now = new Date();
    const timeDiff = now.getTime() - user.lastRefill.getTime();
    const leakedTokens =
      Math.floor(timeDiff / this.REFILL_INTERVAL) * this.LEAK_RATE;

    // Update available tokens
    const newTokens = Math.min(user.maxTokens, user.tokens + leakedTokens);
    const newLastRefill = new Date(
      now.getTime() - (timeDiff % this.REFILL_INTERVAL)
    );

    if (newTokens < 1) {
      return false; // No tokens available
    }

    // Consume one token
    await this.userRepository.updateTokens(
      userId,
      newTokens - 1,
      newLastRefill
    );
    return true;
  }
}

5. GraphQL for PIX Query

I implemented a complete GraphQL schema:

// src/graphql/types.ts
const typeDefs = gql`
  type User {
    id: ID!
    email: String!
    name: String!
  }

  type PixQueryResult {
    success: Boolean!
    pixKey: String!
    value: Float!
    accountHolder: String!
    accountType: String!
    bankName: String!
    message: String!
  }

  type TokenStatus {
    tokens: Int!
    maxTokens: Int!
    lastRefill: String!
  }

  type Query {
    tokenStatus: TokenStatus!
  }

  type Mutation {
    register(email: String!, password: String!, name: String!): AuthResult!
    login(email: String!, password: String!): AuthResult!
    queryPixKey(pixKey: String!, value: Float!): PixQueryResult!
  }
`;

6. Rate Limiting Middleware

The middleware integrates Leaky Bucket with requests:

// src/middleware/leakyBucket.ts
export const leakyBucketMiddleware = async (ctx: Context, next: Next) => {
  const user = ctx.state.user;

  const hasToken = await leakyBucketService.consumeToken(user.userId);

  if (!hasToken) {
    ctx.status = 429; // Too Many Requests
    ctx.body = {
      error: 'Rate limit exceeded',
      message:
        'You have exceeded the request limit. Try again in a few seconds.',
    };
    return;
  }

  await next();
};

🧪 Comprehensive Testing

Unit Tests with Jest

I implemented 68 tests covering all scenarios:

// src/__tests__/leakyBucket.test.ts
describe('LeakyBucketService', () => {
  test('should consume token when available', async () => {
    const service = new LeakyBucketService();
    const result = await service.consumeToken('user1');
    expect(result).toBe(true);
  });

  test('should reject when no tokens', async () => {
    // Consume all tokens
    for (let i = 0; i < 10; i++) {
      await service.consumeToken('user1');
    }

    const result = await service.consumeToken('user1');
    expect(result).toBe(false);
  });
});

Load Testing with k6

I created load testing scripts to validate behavior under stress:

// tests/load/stress-test.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '2m', target: 100 }, // Ramp up
    { duration: '5m', target: 100 }, // Constant load
    { duration: '2m', target: 0 }, // Ramp down
  ],
};

export default function () {
  const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

  const response = http.post(
    'http://localhost:3000/graphql',
    {
      query: `mutation QueryPixKey($pixKey: String!, $value: Float!) {
      queryPixKey(pixKey: $pixKey, value: $value) {
        success pixKey value accountHolder
      }
    }`,
      variables: { pixKey: 'test@example.com', value: 100.5 },
    },
    {
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`,
      },
    }
  );

  check(response, {
    'status is 200': r => r.status === 200,
    'rate limited when needed': r => r.status === 429 || r.status === 200,
  });

  sleep(1);
}

📚 Complete Documentation

Postman Collection

I created a complete collection with all endpoints:

{
  "info": {
    "name": "Leaky Bucket API",
    "description": "Complete API with authentication and rate limiting"
  },
  "item": [
    {
      "name": "Auth",
      "item": [
        {
          "name": "Register",
          "request": {
            "method": "POST",
            "url": "http://localhost:3000/graphql",
            "body": {
              "mode": "raw",
              "raw": "{\"query\":\"mutation Register($email: String!, $password: String!, $name: String!) { register(email: $email, password: $password, name: $name) { success token user { id email name } } }\",\"variables\":{\"email\":\"test@example.com\",\"password\":\"password123\",\"name\":\"Test User\"}}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Detailed README

I documented the entire project with:

📖 Installation and configuration guide
🏗️ Architecture and data flow
🔧 Environment configuration
🧪 How to run tests
📊 Metrics and monitoring
🔒 Security considerations

🚀 Deployment and Configuration

Automation Scripts

I created scripts to facilitate development:

#!/bin/bash
# scripts/setup-env.sh

echo "🚀 Setting up Leaky Bucket environment..."

# Create .env file if it doesn't exist
if [ ! -f .env ]; then
    cat > .env << EOF
# Server Configuration
PORT=3000
NODE_ENV=development

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=24h

# Leaky Bucket
INITIAL_TOKENS=10
MAX_TOKENS=10
LEAK_RATE=1
REFILL_INTERVAL=1000

# Logging
LOG_LEVEL=info

# Tests
TEST_USER_EMAIL=test@example.com
TEST_USER_PASSWORD=password123
TEST_USER_NAME=Test User
EOF
    echo "✅ .env file created successfully!"
else
    echo "ℹ️  .env file already exists"
fi

echo "🎉 Environment configured! Run 'npm run dev' to start the server"

📊 Results and Metrics

Test Performance

68 Jest tests: ✅ All passing
Load tests: ✅ Rate limiting working
Response time: < 100ms for normal requests
Throughput: 1000+ req/s with active rate limiting

Feature Coverage

✅ 100% of mandatory requirements implemented
✅ 93% of bonus requirements implemented
✅ 100% of tests passing
✅ 100% of documentation complete

🔍 Challenges and Solutions

1. Token Synchronization

Challenge: Ensuring tokens are consumed atomically in multi-thread environment.

Solution: Implemented a user-based locking system using Map and atomic operations.

2. Environment Configuration

Challenge: Maintaining consistent configurations between development and production.

Solution: Created environment variable system with validation and default values.

3. Load Testing

Challenge: Simulating realistic load and validating rate limiting.

Solution: Implemented k6 tests with different scenarios (spike, stress, load).

🎯 Lessons Learned

Modular Architecture: Clear separation of responsibilities facilitated testing and maintenance
Comprehensive Testing: Unit + integration + load tests are essential
Documentation: Documenting from the beginning saves time in the future
Configuration: Automating environment setup improves DX
Rate Limiting: Leaky Bucket is more efficient than Token Bucket for specific use cases

🔮 Next Steps

To evolve the system, I would consider:

🔄 Implement Redis for token persistence
📈 Add metrics with Prometheus
🔐 Implement refresh tokens
🌐 Add IP-based rate limiting
📱 Create React + Relay frontend

📝 Conclusion

This project demonstrated the importance of well-thought architecture, comprehensive testing, and complete documentation. The resulting system is robust, scalable, and production-ready.

The Leaky Bucket strategy proved effective for rate limiting, and GraphQL integration provided a flexible and well-documented API.

Complete code: GitHub Repository

Liked the article? Leave a ❤️ and share with other developers!