@davaux/csrf 0.8.0

package/CLAUDE.md

@@ -0,0 +1,95 @@
+<!-- pka-generated -->
+# @davaux/csrf
+
+> Generated by Project Knowledge Analyzer on 2026-06-06T21:53:10.185Z
+
+## Overview
+
+CSRF protection middleware for Davaux
+
+**Version**: 0.8.0
+**Author**: David L Dyess II
+**License**: MIT
+**Repository**: https://codeberg.org/davaux/davaux#readme
+
+## Tech Stack
+
+- **Language**: TypeScript
+- **Module System**: ESM (`type: module`)
+
+## Commands
+
+- `npm run build` — tsc
+- `npm run typecheck` — tsc --noEmit
+
+## Project Structure
+
+```
+├── CLAUDE.md
+├── README.md
+├── package.json
+├── tsconfig.json
+└── src/
+    └── index.ts
+
+```
+
+## Entry Points
+
+- `src/index.ts`
+
+## Files by Type
+
+### Documentation (2)
+- `CLAUDE.md`
+- `README.md`
+
+### Config (2)
+- `package.json`
+- `tsconfig.json`
+
+### Module (1)
+- `src/index.ts`
+
+
+## Git
+- **Branch**: main
+- **Last Commit**: chore: Add alpha status note to README
+- **Author**: David Dyess II
+- **Date**: 2026-06-06 15:52:27 -0600
+- **Remote**: https://codeberg.org/davaux/davaux.git
+
+### Recent Commits
+```
+f527031 chore: Add alpha status note to README
+90c819e chore: Add repo info to package.json files
+b200d9d feat(davaux)!: Add OmlCacheConfig - opt-in with includes option or opt-out with excludes option; Fix OML implementation to follow OML spec - use output instead of return
+3bce0c2 chore: Update and add READMEs to packages; update ROADMAP
+fc27c20 fix(davaux): Remove old dist folder on new builds; fix server port per DavauxConfig
+c760659 feat(davaux): Add minify CSS in production builds
+c899ab8 fix(davaux): Added method JS and JSX extenstion to scanner
+7d99f04 feat(davaux): Add support for declarative partial updates
+3b47f37 chore: Bump package versions to 0.8.0
+aa0460f chore: Add CHANGELOG.md
+```
+
+## Dependencies
+
+
+### Development
+@davaux/session, @types/node, davaux, typescript
+
+
+
+
+
+
+
+
+
+## Exported Symbols
+
+**`src/index.ts`**
+`csrfMiddleware`, `CsrfOptions`
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David L Dyess II
+
+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,57 @@
+# @davaux/csrf
+
+CSRF protection middleware for Davaux. Generates a per-session token and rejects mutating requests (`POST`, `PUT`, `PATCH`, `DELETE`) that don't carry it.
+
+## Installation
+
+```bash
+npm install @davaux/csrf
+```
+
+Requires `@davaux/session`.
+
+## Setup
+
+Register `sessionMiddleware` before `csrfMiddleware`:
+
+```ts
+// davaux.config.ts
+import { defineConfig } from 'davaux/config'
+import { sessionMiddleware } from '@davaux/session'
+import { csrfMiddleware } from '@davaux/csrf'
+
+export default defineConfig({
+  middleware: [
+    sessionMiddleware({ secret: process.env.SESSION_SECRET! }),
+    csrfMiddleware(),
+  ],
+})
+```
+
+## Embedding the token in forms
+
+`ctx.state.csrf.token` is available in every handler and layout:
+
+```tsx
+// src/routes/contact.page.tsx
+export default definePage((ctx) => (
+  <form method="post">
+    <input type="hidden" name="_csrf" value={ctx.state.csrf.token} />
+    <button type="submit">Send</button>
+  </form>
+))
+```
+
+For API clients, send the token in the `x-csrf-token` header instead of a form field.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `field` | `string` | `'_csrf'` | Form field name to check |
+| `header` | `string` | `'x-csrf-token'` | Request header name (case-insensitive) |
+| `sessionKey` | `string` | `'_csrf'` | Session key used to store the token |
+
+## Documentation
+
+[davaux.codeberg.page/docs/csrf](https://davaux.codeberg.page/docs/csrf)

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@davaux/csrf",
+  "version": "0.8.0",
+  "description": "CSRF protection middleware for Davaux",
+  "type": "module",
+  "author": "David L Dyess II",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/davaux/davaux"
+  },
+  "bugs": {
+    "url": "https://codeberg.org/davaux/davaux/issues"
+  },
+  "homepage": "https://codeberg.org/davaux/davaux#readme",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@davaux/session": ">=0.8.0",
+    "davaux": ">=0.8.0"
+  },
+  "devDependencies": {
+    "@davaux/session": "*",
+    "@types/node": "^25.0.0",
+    "davaux": "*",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import type {} from '@davaux/session'
+import type { MiddlewareFn } from 'davaux'
+
+// ─── State augmentation ───────────────────────────────────────────────────────
+
+declare module 'davaux' {
+  interface State {
+    csrf: { token: string }
+  }
+}
+
+// ─── Options ──────────────────────────────────────────────────────────────────
+
+export interface CsrfOptions {
+  /**
+   * Form field name to check on `application/x-www-form-urlencoded` requests.
+   * Default: `'_csrf'`
+   */
+  field?: string
+  /**
+   * Request header name to check (case-insensitive).
+   * Default: `'x-csrf-token'`
+   */
+  header?: string
+  /**
+   * Session key used to store the token.
+   * Default: `'_csrf'`
+   */
+  sessionKey?: string
+}
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+// ─── Middleware ───────────────────────────────────────────────────────────────
+
+/**
+ * CSRF protection middleware. Generates a random token per session and rejects
+ * mutating requests (`POST`, `PUT`, `PATCH`, `DELETE`) that do not carry a
+ * matching token in either the request header or a form field.
+ *
+ * Requires `@davaux/session` — register `sessionMiddleware` before this in
+ * your middleware chain. The current token is available as `ctx.state.csrf.token`
+ * for embedding in forms.
+ *
+ * @example
+ * // _global.ts
+ * import { csrfMiddleware } from '@davaux/csrf'
+ * export default csrfMiddleware({ field: '_csrf' })
+ */
+export function csrfMiddleware(options: CsrfOptions = {}): MiddlewareFn {
+  const field = options.field ?? '_csrf'
+  const headerName = (options.header ?? 'x-csrf-token').toLowerCase()
+  const sessionKey = options.sessionKey ?? '_csrf'
+
+  return async (ctx, next) => {
+    if (!ctx.state.session) {
+      throw new Error('@davaux/csrf: sessionMiddleware must be registered before csrfMiddleware')
+    }
+
+    // Get or generate the token for this session
+    let token = ctx.state.session.get<string>(sessionKey)
+    if (!token) {
+      token = randomBytes(32).toString('hex')
+      ctx.state.session.set(sessionKey, token)
+    }
+    ctx.state.csrf = { token }
+
+    // Safe methods pass through immediately
+    const method = (ctx.req.method ?? 'GET').toUpperCase()
+    if (SAFE_METHODS.has(method)) {
+      return next()
+    }
+
+    // Mutating requests must carry a valid token
+    const submitted = await resolveSubmitted(
+      ctx.req,
+      ctx.req.headers[headerName] as string | undefined,
+      field,
+      ctx,
+    )
+    if (!submitted || !safeEqual(submitted, token)) {
+      ctx.res.writeHead(403, { 'Content-Type': 'text/plain; charset=utf-8' })
+      ctx.res.end('Forbidden: invalid or missing CSRF token')
+      return
+    }
+
+    await next()
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function resolveSubmitted(
+  req: import('node:http').IncomingMessage,
+  headerValue: string | undefined,
+  field: string,
+  ctx: import('davaux').RequestContext,
+): Promise<string | undefined> {
+  if (headerValue) return headerValue
+
+  const contentType = req.headers['content-type'] ?? ''
+  if (contentType.includes('application/x-www-form-urlencoded')) {
+    const body = await ctx.form()
+    return body[field] as string | undefined
+  }
+
+  if (contentType.includes('multipart/form-data')) {
+    const { fields } = await ctx.multipart()
+    return fields[field]
+  }
+
+  return undefined
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const aBuf = Buffer.from(a)
+  const bBuf = Buffer.from(b)
+  if (aBuf.length !== bBuf.length) return false
+  return timingSafeEqual(aBuf, bBuf)
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "skipLibCheck": true,
+    "lib": ["ESNext"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}