@tozielinski/next-upstash-nonce 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Torsten Zielinski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# next-upstash-nonce
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+Create, store, verify and delete nonces in Redis by Upstash for Next.js
+
+# Quick Start
+### Install the package:
+```bash
+npm install @tozielinski/next-upstash-nonce
+```
+### Create database
+Create a new redis database on [upstash](https://console.upstash.com/)
+### Create a NonceManager Instance
+```typescript
+import { NonceManager } from '@tozielinski/next-upstash-nonce'
+import { Redis } from "@upstash/redis";
+
+const redis = new Redis({
+    url: process.env.UPSTASH_REDIS_REST_URL as string,
+    token: process.env.UPSTASH_REDIS_REST_TOKEN as string,
+});
+
+export const nonceManager = new NonceManager(redis, {ttlSeconds: 60* 5});
+```
+### Create a ServerAction, to use it from client side
+```typescript
+'use server'
+
+import {nonceManager} from "@/[wherever you store your nonceManager instance]";
+
+export async function createNonce(): Promise<string> {
+    return await nonceManager.create();
+}
+```
+### Secure your API endpoint
+```typescript
+'use server'
+
+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");
+
+    if (!nonce) {
+        return NextResponse.json(
+            { error: "Missing nonce", valid: false },
+            { status: 401 }
+        );
+    }
+
+    const valid = await nonceManager.verifyAndDelete(nonce);
+
+    return NextResponse.json({nonce: nonce, valid: valid});
+}
+```
+### Use it in your client side
+```typescript
+'use client'
+
+import {useState} from "react";
+import {createNonce} from "@/[wherever you store your server action]";
+
+export default function NonceSecuredComponent() {
+    const [running, setRunning] = useState(false);
+    const [message, setMessage] = useState("");
+
+    const handleClick = async () => {
+        if (running) return;
+        setRunning(true);
+        setMessage("Starting SSA...");
+
+        const nonce = await createNonce();
+
+        const res = await fetch('/api/[name of your API endpoint]', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Nonce': nonce,
+            },
+            body: JSON.stringify({success: true}),
+        });
+
+        if (res.ok) {
+            const data = await res.json();
+            setMessage(`Nonce: ${data.nonce} Valid: ${data.valid}` || "No nonce received");
+            setRunning(false);
+        } else
+            setMessage(res.statusText);
+    }
+
+    return (
+        <div>
+            <button
+                onClick={handleClick}
+                disabled={running}
+                className="px-6 py-3 rounded-xl bg-blue-600 text-white disabled:opacity-50"
+            >
+                {running ? "Running..." : "Start SSA"}
+            </button>
+            <p>{message}</p>
+        </div>
+    )
+}
+```
+

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { Redis } from "@upstash/redis";
+export type NonceOptions = {
+    length?: number;
+    ttlSeconds?: number;
+    prefix?: string;
+};
+export declare class NonceManager {
+    private redis;
+    private length;
+    private ttlSeconds;
+    private prefix;
+    constructor(redis: Redis, opts?: NonceOptions);
+    /**
+     * Generiert einen neuen, kryptographisch sicheren Nonce,
+     * speichert ihn in Redis und gibt ihn zurück.
+     */
+    create(): Promise<string>;
+    /**
+     * Verifiziert einen Nonce: prüft ob vorhanden, und löscht ihn atomisch.
+     * Gibt true zurück, wenn Validierung erfolgreich war (Nonce existierte und wurde entfernt).
+     */
+    verifyAndDelete(nonce: string): Promise<boolean>;
+    /**
+     * Optional: entferne einen Nonce ohne Verifizierung
+     */
+    delete(nonce: string): Promise<void>;
+}
+export default NonceManager;

package/dist/index.js

@@ -0,0 +1,67 @@
+"use strict";
+'use server';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NonceManager = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+class NonceManager {
+    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.prefix = opts.prefix ?? "nonce:";
+    }
+    /**
+     * Generiert einen neuen, kryptographisch sicheren Nonce,
+     * speichert ihn in Redis und gibt ihn zurück.
+     */
+    async create() {
+        const buffer = crypto_1.default.randomBytes(this.length);
+        const nonce = buffer.toString("hex");
+        const key = this.prefix + nonce;
+        console.log("creating nonce:", nonce);
+        // set with ttl (nx not required — collisions extremely unlikely)
+        await this.redis.set(key, "1", { ex: this.ttlSeconds });
+        return nonce;
+    }
+    /**
+     * Verifiziert einen Nonce: prüft ob vorhanden, und löscht ihn atomisch.
+     * Gibt true zurück, wenn Validierung erfolgreich war (Nonce existierte und wurde entfernt).
+     */
+    async verifyAndDelete(nonce) {
+        if (!nonce)
+            return false;
+        //       const key = this.prefix + nonce;
+        //
+        //       const script = `
+        //   local v = redis.call('GET', KEYS[1])
+        //   if v then
+        //     redis.call('DEL', KEYS[1])
+        //     return v
+        //   end
+        //   return nil
+        // `;
+        try {
+            const res = await this.redis.get(`nonce:${nonce}`);
+            // const res = await (this.redis as any).eval(script, { keys: [key] });
+            if (res)
+                await this.redis.del(`nonce:${nonce}`);
+            return res !== null;
+        }
+        catch (err) {
+            console.error("verifyAndDelete error:", err);
+            return false;
+        }
+    }
+    /**
+     * Optional: entferne einen Nonce ohne Verifizierung
+     */
+    async delete(nonce) {
+        const key = this.prefix + nonce;
+        await this.redis.del(key);
+    }
+}
+exports.NonceManager = NonceManager;
+exports.default = NonceManager;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@tozielinski/next-upstash-nonce",
+  "version": "0.1.4",
+  "description": "Create, store, verify and delete nonces in Redis by Upstash for Next.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tozielinski/next-upstash-nonce.git"
+  },
+  "keywords": [
+    "next",
+    "nextjs",
+    "upstash",
+    "nonce",
+    "redis"
+  ],
+  "author": "Torsten Zielinski",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/tozielinski/next-upstash-nonce/issues"
+  },
+  "homepage": "https://github.com/tozielinski/next-upstash-nonce#readme",
+  "dependencies": {
+    "@upstash/redis": "1.22.0",
+    "crypto": "^1.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+'use server'
+
+import { Redis } from "@upstash/redis";
+import crypto from "crypto";
+
+export type NonceOptions = {
+    length?: number; // bytes
+    ttlSeconds?: number; // Time-to-live in Redis
+    prefix?: string;
+};
+
+export class NonceManager {
+    private redis: Redis;
+    private length: number;
+    private ttlSeconds: number;
+    private prefix: string;
+
+
+    constructor(redis: Redis, opts: NonceOptions = {}) {
+        this.redis = redis;
+        this.length = opts.length ?? 32; // default 32 bytes -> 64 hex chars
+        this.ttlSeconds = opts.ttlSeconds ?? 60 * 5; // default 5 minutes
+        this.prefix = opts.prefix ?? "nonce:";
+    }
+
+
+    /**
+     * Generiert einen neuen, kryptographisch sicheren Nonce,
+     * speichert ihn in Redis und gibt ihn zurück.
+     */
+    async create(): Promise<string> {
+        const buffer = crypto.randomBytes(this.length);
+        const nonce = buffer.toString("hex");
+        const key = this.prefix + nonce;
+
+console.log("creating nonce:", nonce);
+// set with ttl (nx not required — collisions extremely unlikely)
+        await this.redis.set(key, "1", { ex: this.ttlSeconds });
+        return nonce;
+    }
+
+
+    /**
+     * Verifiziert einen Nonce: prüft ob vorhanden, und löscht ihn atomisch.
+     * Gibt true zurück, wenn Validierung erfolgreich war (Nonce existierte und wurde entfernt).
+     */
+    async verifyAndDelete(nonce: string): Promise<boolean> {
+        if (!nonce) return false;
+  //       const key = this.prefix + nonce;
+  //
+  //       const script = `
+  //   local v = redis.call('GET', KEYS[1])
+  //   if v then
+  //     redis.call('DEL', KEYS[1])
+  //     return v
+  //   end
+  //   return nil
+  // `;
+
+        try {
+            const res = await (this.redis as any).get(`nonce:${nonce}`);
+            // const res = await (this.redis as any).eval(script, { keys: [key] });
+            if (res) await this.redis.del(`nonce:${nonce}`);
+            return res !== null;
+        } catch (err) {
+            console.error("verifyAndDelete error:", err);
+            return false;
+        }
+    }
+
+
+    /**
+     * Optional: entferne einen Nonce ohne Verifizierung
+     */
+    async delete(nonce: string): Promise<void> {
+        const key = this.prefix + nonce;
+        await this.redis.del(key);
+    }
+}
+
+
+export default NonceManager;

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}