@tozielinski/next-upstash-nonce 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Bug Fixes
+
+* enable type generation ([6df83aa](https://github.com/tozielinski/next-upstash-nonce/commit/6df83aa769f367481231b21f7cac0d3c0297af40))
+
 ## [1.3.0](https://github.com/tozielinski/next-upstash-nonce/compare/v1.2.3...v1.3.0) (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(
@@ -52,9 +52,38 @@ export async function POST(req: Request) {
 
     const valid = await nonceManager.verifyAndDelete(nonce);
 
+    // valid will be true if nonce was found and deleted
+    // false if nonce was not found or expired
+    
     return NextResponse.json({nonce: nonce, valid: valid});
 }
 ```
+or more simple
+```typescript
+'use 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: 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:
+    //
+    // 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});
+}
+```
 ### Use it in your client side
 ```typescript
 'use client'
@@ -64,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;
@@ -104,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

@@ -0,0 +1,78 @@
+import { Redis } from "@upstash/redis";
+export type NonceOptions = {
+    ttlNonce?: number;
+    prefix?: string;
+    ttlRateLimit?: number;
+    countRateLimit?: number;
+};
+export type NonceCheckResult = {
+    valid: true;
+    nonce: string;
+} | {
+    valid: false;
+    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 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,
+     * and returns the nonce string.
+     */
+    create(): Promise<string>;
+    /**
+     * verifies a nonce and deletes it from Redis,
+     * returning true if the nonce exists and has not expired.
+     */
+    verify(nonce: string): Promise<boolean>;
+    /**
+     * verifies a nonce and deletes it from Redis,
+     * returning true if the nonce exists and has not expired.
+     */
+    verifyAndDelete(nonce: string): Promise<boolean>;
+    /**
+     * verifies a nonce from the Header of a request
+     * returns a NonceCheckResult if the nonce exists and has not expired.
+     */
+    verifyNonceFromRequest(req: Request): Promise<NonceCheckResult>;
+    /**
+     * verifies a nonce from the Header of a request and deletes it from Redis
+     * returns a NonceCheckResult if the nonce exists and has not expired.
+     */
+    verifyAndDeleteNonceFromRequest(req: Request): Promise<NonceCheckResult>;
+    /**
+     * 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

@@ -0,0 +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;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.0",
+  "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",