sofi-csrf 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sofidev
+
+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,128 @@
+# Sofi CSRF
+
+A fast, fully-typed, and framework-agnostic CSRF (Cross-Site Request Forgery) protection library tailored for Node.js. It features a standalone Core logic engine with an out-of-the-box adapter specifically designed for Express.js.
+
+## Features
+- **Framework-Agnostic Core**: Secure payload generator and timing-safe verification extracted from the routing logic. Fits any HTTP node server.
+- **TypeScript First**: End-to-end typed classes and functions properly documented with `TSDoc`.
+- **Express Adapter**: Pre-packaged middleware wrapping `req`, `res` and cookies appropriately to effortlessly handle injection and error throwing.
+- **Token Rotation**: Avoid token reuse attacks with the out-of-the-box regeneration middlewares.
+
+## Supported Frameworks & Contributing
+Currently, `sofi-csrf` provides official "out-of-the-box" adapters for:
+- **Express.js**
+- **Hono**
+
+Thanks to its framework-agnostic core engine, we welcome community PRs! Feel free to contribute by creating new adapters (Fastify, Koa, NestJS, etc.) to expand the ecosystem. Likewise, I will be adding more official adapters progressively as time permits.
+
+## Installation
+
+```bash
+npm install sofi-csrf
+```
+
+*(Note for Express adapter: You should also use `cookie-parser` within your Express application)*.
+
+## Usage Guide (Express)
+
+```typescript
+import express from 'express';
+// Note: [cookie-parser](https://www.npmjs.com/package/cookie-parser) is required to extract cookies smoothly before this middleware
+import cookieParser from 'cookie-parser';
+import { expressCsrf } from 'sofi-csrf';
+
+const app = express();
+app.use(express.json());
+app.use(cookieParser());
+
+// 1. Initialize the middleware adapter (Accepts partial options)
+const { csrfMiddleware, verifyCsrfToken, regenerateCsrfToken } = expressCsrf({
+  cookieName: 'xsrf-token', // Defaults to 'csrfToken'
+  cookieOptions: {
+    secure: process.env.NODE_ENV === 'production',
+    httpOnly: true,
+    maxAge: 3600000
+  }
+});
+
+// 2. Inject tokens globally (assigns token to local cookies, req and res.locals)
+app.use(csrfMiddleware);
+
+// 3. Retrieve token for frontend binding or views
+app.get('/form', (req, res) => {
+  // Can be easily retrieved from req.csrfToken, or res.locals.csrfToken inside EJS/Pug templates!
+  res.json({ csrfToken: req.csrfToken });
+});
+
+// 4. Secure your data mutations routes 
+// Client must send the token either in req.body._csrf OR headers['x-csrf-token']
+app.post('/submit', verifyCsrfToken, (req, res) => {
+  res.json({ message: "Successfully executed operation with valid token" });
+});
+
+// 5. Rotate the token 
+// Often necessary when performing high privilege or session-upgrade tasks
+app.post('/sensitive-update', regenerateCsrfToken, (req, res) => {
+   res.json({ message: "Task completed securely. A new token has rolled.", newToken: req.csrfToken });
+});
+```
+
+## Usage Guide (Hono)
+
+```typescript
+import { Hono } from 'hono';
+import { honoCsrf } from 'sofi-csrf';
+
+const app = new Hono();
+
+// 1. Initialize the adapter
+const { csrfMiddleware, verifyCsrfToken, regenerateCsrfToken } = honoCsrf({
+  cookieName: 'xsrf-token',
+});
+
+// 2. Inject token in cookies and set it in context variables (c.get('csrfToken'))
+app.use('*', csrfMiddleware);
+
+// 3. Simple retrieval
+app.get('/form', (c) => {
+  return c.json({ token: c.get('csrfToken') });
+});
+
+// 4. Secure data mutations, accepts 'x-csrf-token' header or '_csrf' in body
+app.post('/submit', verifyCsrfToken, (c) => {
+  return c.text('Processed securely');
+});
+
+// 5. Native Token Rotation
+app.post('/rotate', regenerateCsrfToken, (c) => {
+  return c.json({ message: "Rotated successfully", newToken: c.get('csrfToken') });
+});
+```
+
+## API Documentation
+Explore the code using IDE intelligence to enjoy detailed `TSDocs` snippets and rich context.
+
+### Built-In Interfaces
+- `CsrfCore`: Handpicks the algorithm validations.
+- `CsrfOptions` and `defaultOptions`: Handle customizable rules.
+- `CsrfForbiddenError`: Default thrown exception containing the `403` status.
+
+### Options Configuration
+When initializing your adapter (e.g., `expressCsrf()` or `honoCsrf()`), you can pass an optional configuration object to override the `defaultOptions`. 
+
+Below is the exhaustive list of options you can configure:
+
+| Option | Type | Default Value | Description |
+| :--- | :--- | :--- | :--- |
+| `cookieName` | `string` | `'csrfToken'` | The name of the cookie where the generated token is stored. |
+| `tokenLength` | `number` | `24` | Cryptographic byte length for generation (produces a 48 hexadecimal character string). |
+| `cookieOptions.httpOnly` | `boolean` | `true` | Prevents client-side scripts from accessing the cookie via `document.cookie`. |
+| `cookieOptions.secure` | `boolean` | `process.env.NODE_ENV === 'production'` | Whether to ensure the cookie is only sent over HTTPS. |
+| `cookieOptions.maxAge` | `number` | `3600000` (1 hour) | Expiration time for the cookie in milliseconds. |
+
+---
+
+## Support
+If you found this library helpful, consider supporting my work!
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/sofidev)

package/dist/adapters/express.d.ts

@@ -0,0 +1,34 @@
+import { RequestHandler } from 'express';
+import { CsrfOptions } from '../core/options';
+declare global {
+    namespace Express {
+        interface Request {
+            csrfToken?: string;
+        }
+    }
+}
+/**
+ * Creates an Express compatibility adapter for the CSRF core.
+ * Provides middlewares to inject tokens, verify them, and rotate them on demand.
+ *
+ * @param options - Optional configuration extending defaults.
+ * @returns Three RequestHandlers: csrfMiddleware, verifyCsrfToken, and regenerateCsrfToken.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { expressCsrf } from 'sofi-csrf';
+ *
+ * const app = express();
+ * const { csrfMiddleware, verifyCsrfToken } = expressCsrf();
+ *
+ * app.use(csrfMiddleware);
+ * app.post('/data', verifyCsrfToken, (req, res) => res.send('OK'));
+ * ```
+ */
+export declare function expressCsrf(options?: Partial<CsrfOptions>): {
+    csrfMiddleware: RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;
+    verifyCsrfToken: RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;
+    regenerateCsrfToken: RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;
+};
+//# sourceMappingURL=express.d.ts.map

package/dist/adapters/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/adapters/express.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1E,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAiB,OAAO;YACtB,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB;KACF;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;;;;EAgEzD"}

package/dist/adapters/express.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expressCsrf = expressCsrf;
+const csrf_1 = require("../core/csrf");
+/**
+ * Creates an Express compatibility adapter for the CSRF core.
+ * Provides middlewares to inject tokens, verify them, and rotate them on demand.
+ *
+ * @param options - Optional configuration extending defaults.
+ * @returns Three RequestHandlers: csrfMiddleware, verifyCsrfToken, and regenerateCsrfToken.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { expressCsrf } from 'sofi-csrf';
+ *
+ * const app = express();
+ * const { csrfMiddleware, verifyCsrfToken } = expressCsrf();
+ *
+ * app.use(csrfMiddleware);
+ * app.post('/data', verifyCsrfToken, (req, res) => res.send('OK'));
+ * ```
+ */
+function expressCsrf(options) {
+    const core = new csrf_1.CsrfCore(options);
+    /**
+     * Middleware that injects a valid token into cookies, request, and locals.
+     */
+    const csrfMiddleware = (req, res, next) => {
+        const { cookieName, cookieOptions } = core.getOptions();
+        if (!req.cookies || !req.cookies[cookieName]) {
+            const newToken = core.generateToken();
+            res.cookie(cookieName, newToken, cookieOptions);
+            req.csrfToken = newToken;
+        }
+        else {
+            req.csrfToken = req.cookies[cookieName];
+        }
+        res.locals.csrfToken = req.csrfToken;
+        next();
+    };
+    /**
+     * Middleware that prevents unauthorized modifications.
+     * Only validates data-modifying HTTP methods (POST, PUT, DELETE, PATCH).
+     */
+    const verifyCsrfToken = (req, res, next) => {
+        if (!["POST", "PUT", "DELETE", "PATCH"].includes(req.method)) {
+            return next();
+        }
+        const { cookieName } = core.getOptions();
+        const cookieToken = req.cookies ? req.cookies[cookieName] : undefined;
+        const bodyToken = req.body?._csrf || req.headers["x-csrf-token"];
+        if (!core.verifyToken(cookieToken, bodyToken)) {
+            return next(core.createError());
+        }
+        next();
+    };
+    /**
+     * Middleware that rotates the token immediately after sensitive operations.
+     */
+    const regenerateCsrfToken = (req, res, next) => {
+        if (!["POST", "PUT", "DELETE", "PATCH"].includes(req.method)) {
+            return next();
+        }
+        const { cookieName, cookieOptions } = core.getOptions();
+        const newToken = core.generateToken();
+        res.cookie(cookieName, newToken, cookieOptions);
+        req.csrfToken = newToken;
+        res.locals.csrfToken = newToken;
+        next();
+    };
+    return {
+        csrfMiddleware,
+        verifyCsrfToken,
+        regenerateCsrfToken
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/adapters/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/adapters/express.ts"],"names":[],"mappings":";;AA+BA,kCAgEC;AA9FD,uCAAwC;AAWxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,WAAW,CAAC,OAA8B;IACxD,MAAM,IAAI,GAAG,IAAI,eAAQ,CAAC,OAAO,CAAC,CAAC;IAEnC;;OAEG;IACH,MAAM,cAAc,GAAmB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QACzF,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAExD,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YACtC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;YAChD,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC1C,CAAC;QAED,GAAG,CAAC,MAAM,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;QACrC,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;IAEF;;;OAGG;IACH,MAAM,eAAe,GAAmB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QAC1F,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QAED,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACzC,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACtE,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QAEjE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,SAAS,CAAC,EAAE,CAAC;YAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;IAEF;;OAEG;IACH,MAAM,mBAAmB,GAAmB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QAC9F,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QAED,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QAEtC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;QAChD,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAC;QACzB,GAAG,CAAC,MAAM,CAAC,SAAS,GAAG,QAAQ,CAAC;QAEhC,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;IAEF,OAAO;QACL,cAAc;QACd,eAAe;QACf,mBAAmB;KACpB,CAAC;AACJ,CAAC"}

package/dist/adapters/hono.d.ts

@@ -0,0 +1,34 @@
+import type { Context, Next } from 'hono';
+import { CsrfOptions } from '../core/options';
+declare module 'hono' {
+    interface ContextVariableMap {
+        csrfToken: string;
+    }
+}
+/**
+ * Creates a Hono compatibility adapter for the CSRF core.
+ * Provides middlewares to inject tokens, verify them, and rotate them on demand.
+ *
+ * @param options - Optional configuration extending defaults.
+ * @returns Three RequestHandlers: csrfMiddleware, verifyCsrfToken, and regenerateCsrfToken.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { honoCsrf } from 'sofi-csrf';
+ *
+ * const app = new Hono();
+ * const { csrfMiddleware, verifyCsrfToken } = honoCsrf();
+ *
+ * app.use('*', csrfMiddleware);
+ * app.post('/data', verifyCsrfToken, (c) => c.text('OK'));
+ * ```
+ */
+export declare function honoCsrf(options?: Partial<CsrfOptions>): {
+    csrfMiddleware: (c: Context, next: Next) => Promise<void>;
+    verifyCsrfToken: (c: Context, next: Next) => Promise<void | (Response & import("hono").TypedResponse<{
+        error: string;
+    }, any, "json">)>;
+    regenerateCsrfToken: (c: Context, next: Next) => Promise<void>;
+};
+//# sourceMappingURL=hono.d.ts.map

package/dist/adapters/hono.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/adapters/hono.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG1C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,kBAAkB;QAC1B,SAAS,EAAE,MAAM,CAAC;KACnB;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;wBAOpB,OAAO,QAAQ,IAAI;yBAuBlB,OAAO,QAAQ,IAAI;;;6BA0Cf,OAAO,QAAQ,IAAI;EAoB1D"}

package/dist/adapters/hono.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.honoCsrf = honoCsrf;
+const cookie_1 = require("hono/cookie");
+const csrf_1 = require("../core/csrf");
+/**
+ * Creates a Hono compatibility adapter for the CSRF core.
+ * Provides middlewares to inject tokens, verify them, and rotate them on demand.
+ *
+ * @param options - Optional configuration extending defaults.
+ * @returns Three RequestHandlers: csrfMiddleware, verifyCsrfToken, and regenerateCsrfToken.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { honoCsrf } from 'sofi-csrf';
+ *
+ * const app = new Hono();
+ * const { csrfMiddleware, verifyCsrfToken } = honoCsrf();
+ *
+ * app.use('*', csrfMiddleware);
+ * app.post('/data', verifyCsrfToken, (c) => c.text('OK'));
+ * ```
+ */
+function honoCsrf(options) {
+    const core = new csrf_1.CsrfCore(options);
+    /**
+     * Middleware that injects a valid token into cookies and Hono Context variables.
+     * Exposes token in `c.get('csrfToken')`.
+     */
+    const csrfMiddleware = async (c, next) => {
+        const { cookieName, cookieOptions } = core.getOptions();
+        let token = (0, cookie_1.getCookie)(c, cookieName);
+        if (!token) {
+            token = core.generateToken();
+            // En hono, maxAge es en segundos si no me equivoco, pero respetaremos la interfaz original (milisegundos) o ajustaremos.
+            // Hono setCookie takes maxAge strictly as number (in seconds generally as per standard).
+            // Express maxAge is MS. Let's make it compatible.
+            const honoCookieOpts = { ...cookieOptions, maxAge: Math.floor(cookieOptions.maxAge / 1000) };
+            (0, cookie_1.setCookie)(c, cookieName, token, honoCookieOpts);
+        }
+        // Almacenar variable en el request context
+        c.set('csrfToken', token);
+        await next();
+    };
+    /**
+     * Middleware that prevents unauthorized modifications.
+     * Only validates data-modifying HTTP methods (POST, PUT, DELETE, PATCH).
+     */
+    const verifyCsrfToken = async (c, next) => {
+        if (!["POST", "PUT", "DELETE", "PATCH"].includes(c.req.method)) {
+            return await next();
+        }
+        const { cookieName } = core.getOptions();
+        const cookieToken = (0, cookie_1.getCookie)(c, cookieName);
+        let bodyToken = undefined;
+        // 1. Header lookup (Safest)
+        bodyToken = c.req.header('x-csrf-token');
+        // 2. Body lookup via cloning to prevent destructive reading
+        if (!bodyToken) {
+            const contentType = c.req.header('content-type') || '';
+            try {
+                if (contentType.includes('application/json')) {
+                    const cloned = c.req.raw.clone();
+                    const data = await cloned.json();
+                    bodyToken = data._csrf;
+                }
+                else if (contentType.includes('application/x-www-form-urlencoded') || contentType.includes('multipart/form-data')) {
+                    const cloned = c.req.raw.clone();
+                    const formData = await cloned.formData();
+                    bodyToken = formData.get('_csrf')?.toString();
+                }
+            }
+            catch {
+                // Ignore parse errors, bodyToken will remain undefined
+            }
+        }
+        if (!core.verifyToken(cookieToken, bodyToken)) {
+            const error = core.createError();
+            return c.json({ error: error.message }, error.status);
+        }
+        await next();
+    };
+    /**
+     * Middleware that rotates the token immediately after sensitive operations.
+     */
+    const regenerateCsrfToken = async (c, next) => {
+        if (!["POST", "PUT", "DELETE", "PATCH"].includes(c.req.method)) {
+            return await next();
+        }
+        const { cookieName, cookieOptions } = core.getOptions();
+        const honoCookieOpts = { ...cookieOptions, maxAge: Math.floor(cookieOptions.maxAge / 1000) };
+        const newToken = core.generateToken();
+        (0, cookie_1.setCookie)(c, cookieName, newToken, honoCookieOpts);
+        c.set('csrfToken', newToken);
+        await next();
+    };
+    return {
+        csrfMiddleware,
+        verifyCsrfToken,
+        regenerateCsrfToken
+    };
+}
+//# sourceMappingURL=hono.js.map

package/dist/adapters/hono.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.js","sourceRoot":"","sources":["../../src/adapters/hono.ts"],"names":[],"mappings":"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"}

package/dist/core/csrf.d.ts

@@ -0,0 +1,50 @@
+import { CsrfOptions } from './options';
+import { CsrfForbiddenError } from './errors';
+/**
+ * Core CSRF Token generator and validator.
+ * Framework-agnostic implementation handling secure cryptographic operations.
+ *
+ * @example
+ * ```typescript
+ * const core = new CsrfCore({ tokenLength: 32 });
+ * const token = core.generateToken();
+ * const isValid = core.verifyToken(token, 'user-provided-token');
+ * ```
+ */
+export declare class CsrfCore {
+    private options;
+    /**
+     * Initializes the CSRF Core engine.
+     *
+     * @param options - Optional configuration overriding default properties.
+     */
+    constructor(options?: Partial<CsrfOptions>);
+    /**
+     * Retrieves the current configuration options.
+     *
+     * @returns Current CSRF options.
+     */
+    getOptions(): CsrfOptions;
+    /**
+     * Generates a new secure random token.
+     *
+     * @returns A secure hexadecimal string token.
+     */
+    generateToken(): string;
+    /**
+     * Validates if the token stored in the cookie matches the token sent in the request.
+     * Uses timing-safe equality to prevent timing attacks.
+     *
+     * @param cookieToken - The token retrieved from the trusted HTTP cookie.
+     * @param bodyOrHeaderToken - The token sent by the client via body or headers.
+     * @returns `true` if both tokens match and exist, `false` otherwise.
+     */
+    verifyToken(cookieToken?: string, bodyOrHeaderToken?: string): boolean;
+    /**
+     * Creates an instance of the configured CSRF validation error.
+     *
+     * @returns A CsrfForbiddenError indicating a forbidden action.
+     */
+    createError(): CsrfForbiddenError;
+}
+//# sourceMappingURL=csrf.d.ts.map

package/dist/core/csrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../../src/core/csrf.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAkB,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAAc;IAE7B;;;;OAIG;gBACS,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;IAW1C;;;;OAIG;IACI,UAAU,IAAI,WAAW;IAIhC;;;;OAIG;IACI,aAAa,IAAI,MAAM;IAI9B;;;;;;;OAOG;IACI,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO;IAkB7E;;;;OAIG;IACI,WAAW,IAAI,kBAAkB;CAGzC"}

package/dist/core/csrf.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CsrfCore = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const options_1 = require("./options");
+const errors_1 = require("./errors");
+/**
+ * Core CSRF Token generator and validator.
+ * Framework-agnostic implementation handling secure cryptographic operations.
+ *
+ * @example
+ * ```typescript
+ * const core = new CsrfCore({ tokenLength: 32 });
+ * const token = core.generateToken();
+ * const isValid = core.verifyToken(token, 'user-provided-token');
+ * ```
+ */
+class CsrfCore {
+    options;
+    /**
+     * Initializes the CSRF Core engine.
+     *
+     * @param options - Optional configuration overriding default properties.
+     */
+    constructor(options) {
+        this.options = {
+            ...options_1.defaultOptions,
+            ...options,
+            cookieOptions: {
+                ...options_1.defaultOptions.cookieOptions,
+                ...(options?.cookieOptions || {}),
+            }
+        };
+    }
+    /**
+     * Retrieves the current configuration options.
+     *
+     * @returns Current CSRF options.
+     */
+    getOptions() {
+        return this.options;
+    }
+    /**
+     * Generates a new secure random token.
+     *
+     * @returns A secure hexadecimal string token.
+     */
+    generateToken() {
+        return crypto_1.default.randomBytes(this.options.tokenLength).toString('hex');
+    }
+    /**
+     * Validates if the token stored in the cookie matches the token sent in the request.
+     * Uses timing-safe equality to prevent timing attacks.
+     *
+     * @param cookieToken - The token retrieved from the trusted HTTP cookie.
+     * @param bodyOrHeaderToken - The token sent by the client via body or headers.
+     * @returns `true` if both tokens match and exist, `false` otherwise.
+     */
+    verifyToken(cookieToken, bodyOrHeaderToken) {
+        if (!cookieToken || !bodyOrHeaderToken) {
+            return false;
+        }
+        try {
+            const buffer1 = Buffer.from(cookieToken, 'hex');
+            const buffer2 = Buffer.from(bodyOrHeaderToken, 'hex');
+            if (buffer1.length !== buffer2.length) {
+                return false;
+            }
+            return crypto_1.default.timingSafeEqual(buffer1, buffer2);
+        }
+        catch {
+            return cookieToken === bodyOrHeaderToken;
+        }
+    }
+    /**
+     * Creates an instance of the configured CSRF validation error.
+     *
+     * @returns A CsrfForbiddenError indicating a forbidden action.
+     */
+    createError() {
+        return new errors_1.CsrfForbiddenError();
+    }
+}
+exports.CsrfCore = CsrfCore;
+//# sourceMappingURL=csrf.js.map

package/dist/core/csrf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.js","sourceRoot":"","sources":["../../src/core/csrf.ts"],"names":[],"mappings":";;;;;;AAAA,oDAA4B;AAC5B,uCAAwD;AACxD,qCAA8C;AAE9C;;;;;;;;;;GAUG;AACH,MAAa,QAAQ;IACX,OAAO,CAAc;IAE7B;;;;OAIG;IACH,YAAY,OAA8B;QACxC,IAAI,CAAC,OAAO,GAAG;YACb,GAAG,wBAAc;YACjB,GAAG,OAAO;YACV,aAAa,EAAE;gBACb,GAAG,wBAAc,CAAC,aAAa;gBAC/B,GAAG,CAAC,OAAO,EAAE,aAAa,IAAI,EAAE,CAAC;aAClC;SACF,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACI,UAAU;QACf,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACI,aAAa;QAClB,OAAO,gBAAM,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;;OAOG;IACI,WAAW,CAAC,WAAoB,EAAE,iBAA0B;QACjE,IAAI,CAAC,WAAW,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACvC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;YAChD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;YAEtD,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;gBACrC,OAAO,KAAK,CAAC;YAChB,CAAC;YACD,OAAO,gBAAM,CAAC,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAClD,CAAC;QAAC,MAAM,CAAC;YACN,OAAO,WAAW,KAAK,iBAAiB,CAAC;QAC5C,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,WAAW;QAChB,OAAO,IAAI,2BAAkB,EAAE,CAAC;IAClC,CAAC;CACF;AAvED,4BAuEC"}

package/dist/core/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Standard forbidden error thrown when a CSRF attack is detected
+ * or tokens mismatch.
+ */
+export declare class CsrfForbiddenError extends Error {
+    /** The HTTP status code indicating the error. Always 403. */
+    status: number;
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,6DAA6D;IACtD,MAAM,EAAE,MAAM,CAAC;gBAEV,OAAO,SAAuB;CAK3C"}

package/dist/core/errors.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CsrfForbiddenError = void 0;
+/**
+ * Standard forbidden error thrown when a CSRF attack is detected
+ * or tokens mismatch.
+ */
+class CsrfForbiddenError extends Error {
+    /** The HTTP status code indicating the error. Always 403. */
+    status;
+    constructor(message = "Invalid CSRF token") {
+        super(message);
+        this.name = "CsrfForbiddenError";
+        this.status = 403;
+    }
+}
+exports.CsrfForbiddenError = CsrfForbiddenError;
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAC3C,6DAA6D;IACtD,MAAM,CAAS;IAEtB,YAAY,OAAO,GAAG,oBAAoB;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;IACpB,CAAC;CACF;AATD,gDASC"}

package/dist/core/options.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Global default options used for the initial setup.
+ */
+export declare const defaultOptions: CsrfOptions;
+/**
+ * Configuration options for the CSRF protections.
+ */
+export interface CsrfOptions {
+    /** The name of the cookie to store the token. Defaults to 'csrfToken' */
+    cookieName: string;
+    /** Security and lifetime options for the cookie */
+    cookieOptions: {
+        /** Prevent client-side JS from accessing the cookie */
+        httpOnly: boolean;
+        /** Require HTTPS (usually set to true in production automatically) */
+        secure: boolean;
+        /** Cookie lifetime in milliseconds. Defaults to 1 hour */
+        maxAge: number;
+    };
+    /** Length of the random bytes generator. Output will be hex (x2 string length). */
+    tokenLength: number;
+}
+//# sourceMappingURL=options.d.ts.map

package/dist/core/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/core/options.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,WAQ5B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,aAAa,EAAE;QACb,uDAAuD;QACvD,QAAQ,EAAE,OAAO,CAAC;QAClB,sEAAsE;QACtE,MAAM,EAAE,OAAO,CAAC;QAChB,0DAA0D;QAC1D,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/core/options.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultOptions = void 0;
+/**
+ * Global default options used for the initial setup.
+ */
+exports.defaultOptions = {
+    cookieName: 'csrfToken',
+    cookieOptions: {
+        httpOnly: true,
+        secure: process.env.NODE_ENV === 'production',
+        maxAge: 3600000,
+    },
+    tokenLength: 24,
+};
+//# sourceMappingURL=options.js.map

package/dist/core/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/core/options.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACU,QAAA,cAAc,GAAgB;IACzC,UAAU,EAAE,WAAW;IACvB,aAAa,EAAE;QACb,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QAC7C,MAAM,EAAE,OAAO;KAChB;IACD,WAAW,EAAE,EAAE;CAChB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { CsrfCore } from './core/csrf';
+export { CsrfOptions, defaultOptions } from './core/options';
+export { CsrfForbiddenError } from './core/errors';
+export { expressCsrf } from './adapters/express';
+export { honoCsrf } from './adapters/hono';
+//# 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":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.honoCsrf = exports.expressCsrf = exports.CsrfForbiddenError = exports.defaultOptions = exports.CsrfCore = void 0;
+var csrf_1 = require("./core/csrf");
+Object.defineProperty(exports, "CsrfCore", { enumerable: true, get: function () { return csrf_1.CsrfCore; } });
+var options_1 = require("./core/options");
+Object.defineProperty(exports, "defaultOptions", { enumerable: true, get: function () { return options_1.defaultOptions; } });
+var errors_1 = require("./core/errors");
+Object.defineProperty(exports, "CsrfForbiddenError", { enumerable: true, get: function () { return errors_1.CsrfForbiddenError; } });
+var express_1 = require("./adapters/express");
+Object.defineProperty(exports, "expressCsrf", { enumerable: true, get: function () { return express_1.expressCsrf; } });
+var hono_1 = require("./adapters/hono");
+Object.defineProperty(exports, "honoCsrf", { enumerable: true, get: function () { return hono_1.honoCsrf; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,oCAAuC;AAA9B,gGAAA,QAAQ,OAAA;AACjB,0CAA6D;AAAvC,yGAAA,cAAc,OAAA;AACpC,wCAAmD;AAA1C,4GAAA,kBAAkB,OAAA;AAC3B,8CAAiD;AAAxC,sGAAA,WAAW,OAAA;AACpB,wCAA2C;AAAlC,gGAAA,QAAQ,OAAA"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "sofi-csrf",
+  "version": "1.0.0",
+  "description": "Fast, fully-typed, and framework-agnostic CSRF protection library for Node.js. Works with Express and Hono.",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest",
+    "build": "tsc",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": [
+    "csrf",
+    "security",
+    "express",
+    "hono",
+    "middleware",
+    "framework-agnostic"
+  ],
+  "author": "sofidev",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/cookie-parser": "^1.4.10",
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.5.2",
+    "@types/supertest": "^7.2.0",
+    "cookie-parser": "^1.4.7",
+    "express": "^5.2.1",
+    "hono": "^4.12.10",
+    "jest": "^30.3.0",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.9",
+    "typescript": "^6.0.2"
+  },
+  "types": "dist/index.d.ts"
+}