@tozielinski/next-upstash-nonce 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.4.0](https://github.com/tozielinski/next-upstash-nonce/compare/v1.3.1...v1.4.0) (2025-11-25)
+
+
+### Features
+
+* add rate limiter for API endpoints ([5990ac4](https://github.com/tozielinski/next-upstash-nonce/commit/5990ac49da90984769aa92ab338e6876af30a4b6))
+
 ## [1.3.1](https://github.com/tozielinski/next-upstash-nonce/compare/v1.3.0...v1.3.1) (2025-11-22)
 
 

package/README.md

@@ -2,7 +2,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://img.shields.io/npm/v/%40tozielinski%2Fnext-upstash-nonce)](https://www.npmjs.com/package/@tozielinski/next-upstash-nonce)
 
-## Create, store, verify and delete nonces in Redis by Upstash for Next.js
+## Create, store, verify and delete nonces in Redis by Upstash for Next.js and/or secure your API endpoints with a rate limiter
 
 # Quick Start
 ### Install the package:
@@ -33,7 +33,7 @@ export async function createNonce(): Promise<string> {
     return await nonceManager.create();
 }
 ```
-### Secure your API endpoint
+### Secure your API endpoint with a Nonce
 ```typescript
 'use server'
 
@@ -41,7 +41,7 @@ import {NextResponse} from "next/server";
 import {nonceManager} from "@/[wherever you store your nonceManager instance]";
 
 export async function POST(req: Request) {
-    const nonce = req.headers.get("x-api-nonce");
+    const nonce: boolean = req.headers.get("x-api-nonce");
 
     if (!nonce) {
         return NextResponse.json(
@@ -61,15 +61,25 @@ export async function POST(req: Request) {
 or more simple
 ```typescript
 'use server'
-mport {NextResponse} from "next/server";
+import {NextResponse} from "next/server";
 import {nonceManager} from "@/[wherever you store your nonceManager instance]";
+import {NonceCheckResult} from "@tozielinski/next-upstash-nonce";
 
 export async function POST(req: Request) {
-    const result = await nonceManager.verifyAndDeleteNonceFromRequest(req);
+    const result: NonceCheckResult = await nonceManager.verifyAndDeleteNonceFromRequest(req);
 
     // result will be {nonce: string, valid: true} or
     // {valid false, reason: string, response: NextResponse}
-    // if nonce was not found or expired
+    // if nonce was not found or expired:
+    //
+    // export type NonceCheckResult = | {
+    //     valid: true;
+    //     nonce: string
+    // } | {
+    //     valid: false;
+    //     reason: 'missing-header' | 'invalid-or-expired';
+    //     response: Response
+    // };
     
     return NextResponse.json({nonce: result.nonce, valid: result.valid});
 }
@@ -83,7 +93,7 @@ import {createNonce} from "@/[wherever you store your server action]";
 
 export default function NonceSecuredComponent() {
     const [running, setRunning] = useState(false);
-    const [message, setMessage] = useState("");
+    const [message, setMessage] = useState('');
 
     const handleClick = async () => {
         if (running) return;
@@ -123,4 +133,32 @@ export default function NonceSecuredComponent() {
     )
 }
 ```
+### Secure your API endpoint with a Rate Limiter
+```typescript
+'use server'
+import {NextResponse} from "next/server";
+import {nonceManager} from "@/[wherever you store your nonceManager instance]";
+import {RateLimitResult} from "@tozielinski/next-upstash-nonce";
 
+export async function POST(req: Request) {
+    const rateLimiter: RateLimitResult = await nonceManager.rateLimiter(req!);
+
+    // result will be {valid: true, ip: string, requests: number} or
+    // {valid false, ip:string, requests: number, reason: string, response: NextResponse}
+    // if rate limit was reached or broken:
+    //
+    // export type RateLimitResult = | {
+    //     valid: true;
+    //     ip: string;
+    //     requests: number;
+    // } | {
+    //     valid: false;
+    //     ip: string;
+    //     requests: number;
+    //     reason: `too-many-requests: ${number}`;
+    //     response: Response;
+    // };
+
+    return NextResponse.json({valid: result.valid, ip: result.ip, requests: result.requests});
+}
+```

package/dist/index.d.ts

@@ -1,23 +1,44 @@
 import { Redis } from "@upstash/redis";
 export type NonceOptions = {
-    length?: number;
-    ttlSeconds?: number;
+    ttlNonce?: number;
     prefix?: string;
+    ttlRateLimit?: number;
+    countRateLimit?: number;
 };
 export type NonceCheckResult = {
     valid: true;
     nonce: string;
 } | {
     valid: false;
-    reason: "missing-header" | "invalid-or-expired";
+    reason: 'missing-header' | 'invalid-or-expired';
+    response: Response;
+};
+export type RateLimitResult = {
+    valid: true;
+    ip: string;
+    requests: number;
+} | {
+    valid: false;
+    ip: string;
+    requests: number;
+    reason: `too-many-requests: ${number}`;
     response: Response;
 };
 export declare class NonceManager {
     private redis;
-    private length;
-    private ttlSeconds;
+    private ttlNonce;
     private prefix;
+    private ttlRateLimit;
+    private countRateLimit;
     constructor(redis: Redis, opts?: NonceOptions);
+    /**
+     * makes option parameters available in the server in environment files
+     */
+    private getEnvValue;
+    /**
+     * extracts client IP from request headers
+     */
+    private getClientIp;
     /**
      * generates a new, secure nonce,
      * inserts it into Redis with a TTL,
@@ -48,6 +69,10 @@ export declare class NonceManager {
      * Optional: delete a nonce from Redis manually
      */
     delete(nonce: string): Promise<void>;
+    /**
+     * rate limits requests from the same IP address
+     */
+    rateLimiter(req: Request): Promise<RateLimitResult>;
 }
 export default NonceManager;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,MAAM,MAAM,YAAY,GAAG;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAK;IAC7B,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,MAAM,CAAA;CAChB,GAAG;IACA,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,gBAAgB,GAAG,oBAAoB,CAAC;IAChD,QAAQ,EAAE,QAAQ,CAAA;CACrB,CAAC;AAEF,qBAAa,YAAY;IACrB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAS;gBAGX,KAAK,EAAE,KAAK,EAAE,IAAI,GAAE,YAAiB;IAQjD;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAS/B;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa7C;;;OAGG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAetD;;;OAGG;IACG,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoCrE;;;OAGG;IACG,+BAA+B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoC9E;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAI7C;AAGD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,MAAM,MAAM,YAAY,GAAG;IAEvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAK;IAC7B,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,MAAM,CAAA;CAChB,GAAG;IACA,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,gBAAgB,GAAG,oBAAoB,CAAC;IAChD,QAAQ,EAAE,QAAQ,CAAA;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAK;IAC5B,KAAK,EAAE,IAAI,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;CACpB,GAAG;IACA,KAAK,EAAE,KAAK,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,sBAAsB,MAAM,EAAE,CAAC;IACvC,QAAQ,EAAE,QAAQ,CAAC;CACtB,CAAC;AAEF,qBAAa,YAAY;IACrB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAS;gBAGnB,KAAK,EAAE,KAAK,EAAE,IAAI,GAAE,YAAiB;IAQjD;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAanB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAU/B;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa7C;;;OAGG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAetD;;;OAGG;IACG,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoCrE;;;OAGG;IACG,+BAA+B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoC9E;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1C;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC;CAgB5D;AAED,eAAe,YAAY,CAAC"}

package/dist/index.js

@@ -5,14 +5,41 @@ exports.NonceManager = void 0;
 const uuid_1 = require("uuid");
 class NonceManager {
     redis;
-    length;
-    ttlSeconds;
+    ttlNonce;
     prefix;
+    ttlRateLimit;
+    countRateLimit;
     constructor(redis, opts = {}) {
         this.redis = redis;
-        this.length = opts.length ?? 32; // default 32 bytes -> 64 hex chars
-        this.ttlSeconds = opts.ttlSeconds ?? 60 * 5; // default 5 minutes
+        this.ttlNonce = opts.ttlNonce ?? 60; // default 1 minute
         this.prefix = opts.prefix ?? "nonce:";
+        this.ttlRateLimit = opts.ttlRateLimit ?? 60; // default 1 minute
+        this.countRateLimit = opts.countRateLimit ?? 5; // default 5 times
+    }
+    /**
+     * makes option parameters available in the server in environment files
+     */
+    getEnvValue(name, fallback) {
+        const val = process.env[name];
+        const num = Number(val);
+        if (val === undefined || isNaN(num)) {
+            return fallback;
+        }
+        return num;
+    }
+    /**
+     * extracts client IP from request headers
+     */
+    getClientIp(req) {
+        const forwardedFor = req.headers.get("x-forwarded-for");
+        if (forwardedFor) {
+            return forwardedFor.split(",")[0].trim();
+        }
+        const realIp = req.headers.get("x-real-ip");
+        if (realIp) {
+            return realIp;
+        }
+        return "unknown";
     }
     /**
      * generates a new, secure nonce,
@@ -22,7 +49,8 @@ class NonceManager {
     async create() {
         const nonce = (0, uuid_1.v4)();
         const key = this.prefix + nonce;
-        await this.redis.set(key, "1", { ex: this.ttlSeconds });
+        const ttl = this.getEnvValue("NONCE_TTL_SECONDS", this.ttlNonce);
+        await this.redis.set(key, "1", { ex: ttl });
         return nonce;
     }
     /**
@@ -123,6 +151,22 @@ class NonceManager {
         const key = this.prefix + nonce;
         await this.redis.del(key);
     }
+    /**
+     * rate limits requests from the same IP address
+     */
+    async rateLimiter(req) {
+        const ip = this.getClientIp(req);
+        const key = `rate:${ip}`;
+        const requests = (await this.redis.incr(key)) ?? 0;
+        if (requests === 1) {
+            await this.redis.expire(key, this.getEnvValue("RATE_LIMIT_TTL_SECONDS", this.ttlRateLimit)); // counter runs 60s
+        }
+        if (requests > this.getEnvValue("RATE_LIMIT_COUNT", this.countRateLimit)) {
+            const response = Response.json({ error: "Too many requests" }, { status: 429 });
+            return { valid: false, ip, requests, reason: `too-many-requests: ${requests}`, response: response };
+        }
+        return { valid: true, ip, requests };
+    }
 }
 exports.NonceManager = NonceManager;
 exports.default = NonceManager;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tozielinski/next-upstash-nonce",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Create, store, verify and delete nonces in Redis by Upstash for Next.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",