chore(examples): update examples for v4 compatibility

* Delete useless simple example
* Refactor "complete" example to work with v4 API
* Add a superior and more complete example using React

Author: psibean

.gitignore

@@ -19,4 +19,7 @@ dist/
 
 # example
 example/**/package-lock.json
-example/**/yarn.lock
+example/**/yarn.lock
+
+.vite
+.env

biome.json

@@ -24,12 +24,21 @@
     }
   },
   "overrides": [
+    {
+      "include": ["src/tests", "example/"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noExplicitAny": "off"
+          }
+        }
+      }
+    },
     {
       "include": ["src/tests"],
       "linter": {
         "rules": {
           "suspicious": {
-            "noExplicitAny": "off",
             "noExportsInTest": "off"
           },
           "style": {

example/complete/package.json

@@ -12,7 +12,8 @@
   "license": "ISC",
   "dependencies": {
     "cookie-parser": "^1.4.6",
-    "csrf-csrf": "file:../..",
-    "express": "^4.19.2"
+    "csrf-csrf": "file:../../csrf-csrf-3.2.0.tgz",
+    "express": "^4.19.2",
+    "express-session": "1.18.1"
   }
 }

example/complete/src/index.js

@@ -1,6 +1,7 @@
 import cookieParser from "cookie-parser";
 import { doubleCsrf } from "csrf-csrf";
 import express from "express";
+import session from "express-session";
 
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -12,22 +13,35 @@ const __dirname = path.dirname(__filename);
 const PORT = 3000;
 const CSRF_SECRET = "super csrf secret";
 const COOKIES_SECRET = "super cookie secret";
-const CSRF_COOKIE_NAME = "x-csrf-token";
+const SESSION_SECRET = "stupid session secret";
 
 const app = express();
 app.use(express.json());
+app.use(
+  session({
+    secret: SESSION_SECRET,
+    resave: false,
+    saveUninitialized: true,
+    // maxAge is 1 hour in ms
+    cookie: { secure: false, sameSite: "lax", signed: true, maxAge: 3.6e6 },
+    // No session store configured is bad, this is not representative of a production config
+  }),
+);
+
+// The cookie secret isn't needed for csrf-csrf, but is needed if you want to use
+// cookie-parser to set signed cookies
+app.use(cookieParser(COOKIES_SECRET));
 
 // These settings are only for local development testing.
 // Do not use these in production.
 // In production, ensure you're using cors and helmet and have proper configuration.
 const { invalidCsrfTokenError, generateCsrfToken, doubleCsrfProtection } = doubleCsrf({
   getSecret: () => CSRF_SECRET,
-  cookieName: CSRF_COOKIE_NAME,
-  cookieOptions: { sameSite: false, secure: false }, // not ideal for production, development only
+  getSessionIdentifier: (req) => req.session.id,
+  cookieName: "xsrf_token",
+  cookieOptions: { sameSite: "strict", secure: false },
 });
 
-app.use(cookieParser(COOKIES_SECRET));
-
 // Error handling, validation error interception
 const csrfErrorHandler = (error, req, res, next) => {
   if (error === invalidCsrfTokenError) {

example/react/README.md

@@ -0,0 +1,84 @@
+# React Example
+
+This example intends to be a generic example of how to use `csrf-csrf`. Whilst the example is React based the backend configuration is catered to serving a Single Page Application (SPA), or any client which is being independently hosted of the API. The example assumes that the frontend is hosted cross-site to the backend API. In a case where the frontend is not hosted cross-site to the backend you would want to ensure the CSRF cookie has `sameSite` set to `strict`.
+
+If you aren't sure whether requests from your frontend to your backend are considered cross-site, check the ["What is considered a cross-site request?"](../../FAQ.md#additional-resources) in the FAQ.
+
+For this particular example it would actually be better to use `csrf-sync` instead, however this is for demonstrative purposes of `csrf-csrf`.
+
+The React app attempts to take on and follow the principles of [bulletproof-react](https://github.com/alan2207/bulletproof-react/tree/master/apps/react-vite) but does not do so exhaustively as it is just an example, the backend attempts to translate the same principles.
+
+## Running the example
+
+### With Docker
+
+The example will make use of the below ports, so make sure these ports are available, otherwise you can change them in the `docker-compose.yml` configuration.
+
+* 3700 for the frontend client (react)
+* 3710 for the backend API (express port)
+* 3779 for redis (6379 on the container) (this is only needed if you want to run the backend API locally instead of within docker)
+* 9229 for remote debugging of the backend
+
+In `backend` run:
+
+```bash
+npm install
+npm run build
+```
+
+Then from this directory (`example/react`) run:
+
+```bash
+docker compose up -d
+```
+Once the containers are up and running, you should find the React app at http://localhost:3700/
+
+Tear it down with
+
+```bash
+docker compose down
+```
+from the same directory.
+
+#### Docker Watch Mode
+
+If you want to make changes to the backend and have them update automatically whilst running with Docker, make sure to run `npm run watch` within `backend` from a terminal. Changes will be applied without needing to rebuild or restart the container.
+
+For the client, the Vite watch mode is enabled by default. Any changes made to the client will be replicated in the container, hot reloading will work as expected.
+
+### Without Docker
+
+By default Docker is much easier, however you can run without Docker.
+
+1. Run `npm install` in both `backend` and `client`
+2. Create a `.env` file in `backend` and populate it appropriately:
+
+```
+EXAMPLE_CSRF_SECRET=Fake CSRF secret
+EXAMPLE_ALLOWED_ORIGINS="http://localhost:3700"
+EXAMPLE_API_PORT=3710
+EXAMPLE_SESSION_SECRET=Fake session secret
+EXAMPLE_REDIS_HOST=localhost
+EXAMPLE_REDIS_PORT=3779
+NODE_ENV=development
+```
+3. Create a `.env` file in `client` and populate it appropriately:
+
+```
+VITE_EXAMPLE_BASE_API_URL=http://localhost:3710
+```
+4. Make sure you have a working `redis` instance and that it's configured appropriately in the above environment files
+    * You could run via Docker first (as above) and then stop the `csrf-client` and `csrf-backend` containers, leaving the `csrf-redis` container.
+    * Alternatively give the `redis` service a docker-compose profile and only run that.
+5. Run `npm run dev` in `backend` from one terminal
+6. Run `npm run dev` in `client` from another terminal
+
+### Development
+
+For local development of the example you will want to run `npm install` under both of the `client` and the `backend`. Once you have the containers running, if you want or need to install a new dependency, you'll need to re-run `npm install` on the container as well. You can do this by connecting to the container and running `npm install` from the `/app` directory
+
+```bash
+docker exec -it csrf-backend sh
+docker exec -it csrf-client sh
+```
+

example/react/backend/Dockerfile

@@ -0,0 +1,11 @@
+FROM node:22-alpine
+WORKDIR /app
+COPY . .
+RUN npm install
+RUN npm run build
+# Installing nodemon on the container to not pollute host
+RUN npm install -g nodemon
+EXPOSE 4000
+EXPOSE 9229
+# We need to run legacy watch mode for it to work on the container via polling for Windows host
+CMD ["nodemon",  "-L", "--watch dist", "--inspect=0.0.0.0", "dist/server.js"]

example/react/backend/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "csrf-csrf-react-backend",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "watch": "tsc --watch",
+    "dev": "tsx -r dotenv/config --watch src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "author": "psibean",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "@types/cookie-parser": "1.4.8",
+    "@types/cors": "2.8.17",
+    "@types/express": "5.0.1",
+    "@types/express-session": "1.18.1",
+    "dotenv": "^16.5.0",
+    "tsx": "4.19.3",
+    "typescript": "5.8.3"
+  },
+  "dependencies": {
+    "connect-redis": "8.0.3",
+    "cookie-parser": "1.4.7",
+    "cors": "2.8.5",
+    "csrf-csrf": "file:./csrf-csrf-3.2.2.tgz",
+    "ejs": "3.1.10",
+    "express": "5.1.0",
+    "express-session": "1.18.1",
+    "helmet": "8.1.0",
+    "ioredis": "5.6.1"
+  }
+}

example/react/backend/src/config/constants.ts

@@ -0,0 +1,11 @@
+// Used for environment variable exports
+export const EXAMPLE_API_PORT = Number(process.env.EXAMPLE_API_PORT);
+// You shouldn't really do this forced casting, instead you should check if the environment
+// variables are defined, and if they aren't throw an error to prevent starting up a system
+// that is misconfigured. Or have some alternative but handled approach.
+export const EXAMPLE_ALLOWED_ORIGINS = (process.env.EXAMPLE_ALLOWED_ORIGINS as string).split(",");
+export const EXAMPLE_SESSION_SECRET = (process.env.EXAMPLE_SESSION_SECRET as string) ?? "assdafasdf";
+export const EXAMPLE_CSRF_SECRET = (process.env.EXAMPLE_CSRF_SECRET as string) ?? "sdfgvsarg35g345";
+export const EXAMPLE_REDIS_HOST = process.env.EXAMPLE_REDIS_HOST;
+export const EXAMPLE_REDIS_PORT = Number(process.env.EXAMPLE_REDIS_PORT);
+export const IS_PRODUCTION = process.env.NODE_ENV !== "development";

example/react/backend/src/config/cors.ts

@@ -0,0 +1,11 @@
+import expressCors from "cors";
+import { EXAMPLE_ALLOWED_ORIGINS } from "./constants.js";
+
+console.log(`Configuring cors with origin: '${EXAMPLE_ALLOWED_ORIGINS}'`);
+
+const cors = expressCors({
+  origin: EXAMPLE_ALLOWED_ORIGINS,
+  credentials: true,
+});
+
+export default cors;

example/react/backend/src/config/csrf.ts

@@ -0,0 +1,22 @@
+import { doubleCsrf } from "csrf-csrf";
+import { EXAMPLE_CSRF_SECRET, IS_PRODUCTION } from "./constants.js";
+
+/*
+ * This configuration is for the React SPA.
+ * It is assumed the React SPA is going to be hosted cross-site from the backend API.
+ * If the React SPA was not being hosted cross-site, or was being served directly by the express
+ * app (via static files), then we would want to leave the cookie as strict and we would want to
+ * ensure the cookieName has a secure prefix in production.
+ *
+ * Please note that with the default options secure is set to true in this configuration
+ */
+export const { doubleCsrfProtection, invalidCsrfTokenError, generateCsrfToken } = doubleCsrf({
+  getSecret: () => EXAMPLE_CSRF_SECRET,
+  getSessionIdentifier: (req) => {
+    // If you were using a JWT as a httpOnly cookie, you would return that here instead
+    return req.session.id;
+  },
+  cookieOptions: { sameSite: "lax" },
+  // You always want to prefer a __Host- or __Secure- prefix in production
+  cookieName: IS_PRODUCTION ? "__Host-xsrf-token" : "xsrf-token",
+});