@pronghorn/csrf

CSRF

CSRF is a lightweight, TypeScript-first Cross-Site Request Forgery protection middleware built as an external plugin for Pronghorn. It implements the double-submit cookie pattern, issuing a signed token cookie and verifying it against a header or body field on every mutating request.

Built as a standalone package (@pronghorn/csrf), layers on top of @pronghorn/cookie's signing primitives, completing the security trio alongside @pronghorn/shield (headers) and @pronghorn/cookie (signed cookies).

Why CSRF

@pronghorn/shield hardens response headers and @pronghorn/cookie handles signed cookies, but neither protects against a malicious site silently submitting authenticated requests on a user's behalf. CSRF closes that gap with the double-submit cookie pattern, a widely used, stateless approach that doesn't require server-side session storage.

• Issues a signed, unpredictable token cookie automatically on first request, no manual setup per route.
• Verifies the token via a request header (X-CSRF-Token by default) or a body field, your choice per client type.
• Safe HTTP methods (GET, HEAD, OPTIONS) are exempt by default, since they shouldn't mutate state anyway.
• Works statelessly, no session store dependency, though it composes cleanly with @pronghorn/session if you use one.
• Built directly on @pronghorn/cookie's HMAC signing and timing-safe verification, no duplicated crypto logic.
• Zero additional runtime dependencies beyond @pronghorn/cookie.

Installation

bun add @pronghorn/csrf @pronghorn/cookie

Requires Bun >=1.3.0 and pronghorn >=0.1.2 as a peer dependency (used for typing the middleware only). @pronghorn/cookie is a direct runtime dependency for its signing/parsing primitives.

Quick Start

import { createApp } from 'pronghorn'
import { csrf } from '@pronghorn/csrf'

const app = createApp()

app.use(csrf({ secret: process.env.CSRF_SECRET ?? 'dev-secret' }))

app.get('/form', context => {
  return context.json({ csrfToken: context.locals.csrfToken })
})

app.post('/transfer', context => {
  return context.json({ transferred: true }) // only reached if the token matched
})

await app.listen(4000)

Core Concepts

How the double-submit pattern works

On every request, CSRF ensures a signed token cookie exists (issuing one if missing) and exposes the raw token via context.locals.csrfToken. On mutating requests, it checks that the client echoed the exact same token back via a header or body field, an attacker's site can trigger a request with the victim's cookies attached, but can't read the cookie's value to forge a matching header, since cookies are same-origin but the header must be set by JavaScript the attacker doesn't control.

Embedding the token in a form

Expose the token to a server-rendered view, then include it as a hidden field or send it back as a header from client-side JS.

app.get('/checkout', context => {
  const render = context.get<(view: string, data?: Record<string, unknown>) => Promise<Response>>('render')
  return render('checkout', { csrfToken: context.locals.csrfToken })
})

<!-- views/checkout.fawn -->
<form method="POST" action="/checkout">
  <input type="hidden" name="_csrf" value="{{ csrfToken }}" />
  <button type="submit">Pay</button>
</form>

Sending the token via header (SPA/fetch clients)

const response = await fetch('/form')
const { csrfToken } = await response.json()

await fetch('/transfer', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': csrfToken
  },
  body: JSON.stringify({ amount: 100 })
})

Exempting additional methods or routes

GET, HEAD, and OPTIONS are exempt by default since they shouldn't mutate state. Extend the exempt list if you have other safe, idempotent endpoints.

app.use(csrf({
  secret: process.env.CSRF_SECRET!,
  ignoreMethods: ['GET', 'HEAD', 'OPTIONS', 'TRACE']
}))

Body-field fallback

If a client can't set custom headers (e.g. a traditional HTML form POST), CSRF falls back to reading a body field. This requires body parsing to run first, so register @pronghorn/bodies' bodyParser() before csrf() in the middleware chain.

import { bodyParser } from '@pronghorn/bodies'
import { csrf } from '@pronghorn/csrf'

app.use(bodyParser())
app.use(csrf({ secret: process.env.CSRF_SECRET!, fieldName: '_csrf' }))

Middleware Options

Option	Type	Default	Description
secret	string	-	Required. HMAC signing secret for the token cookie
cookieName	string	'csrf_token'	Name of the signed token cookie
headerName	string	'x-csrf-token'	Header checked for the submitted token
fieldName	string	'_csrf'	Body field checked as a fallback if the header is absent
ignoreMethods	string[]	['GET', 'HEAD', 'OPTIONS']	HTTP methods exempt from verification
tokenLength	number	32	Number of random bytes used to generate each token

API Reference

csrf(options: CsrfOptions): Middleware - global middleware factory, register via app.use(csrf(options)).

Locals property	Type	Description
context.locals.csrfToken	string	The current request's raw (unsigned) CSRF token, safe to embed in forms or return to a client

Architecture

CSRF is implemented as a single middleware module that reuses @pronghorn/cookie's exported primitives rather than reimplementing signing logic.

Responsibility	Implementation
Token generation	crypto.getRandomValues produces cryptographically random bytes, hex-encoded
Token signing/verification	@pronghorn/cookie's signValue/unsignValue (HMAC-SHA256, timing-safe comparison)
Token delivery to client	Signed cookie (httpOnly, sameSite: 'Strict') plus context.locals.csrfToken for embedding in responses
Token verification	Header lookup first, body field fallback second, compared against the unsigned cookie value

Because the check compares the submitted token against the unsigned cookie value (not the raw signed cookie string), a forged header value can never match unless the attacker can read the legitimate cookie, which same-origin policy prevents.

Security Notes

• Always use a long, random secret, distinct from your session or JWT secrets, and load it from an environment variable.
• The cookie is set with sameSite: 'Strict' by default, which alone blocks most cross-site submission vectors, CSRF token verification is a defense-in-depth layer on top of that.
• Never expose the CSRF secret to the client, only the per-request unsigned token (via context.locals.csrfToken) should ever reach the browser.
• If you exempt additional methods via ignoreMethods, make sure those routes are genuinely side-effect-free, exempting a mutating route defeats the protection entirely.

License

WTFPL (Do What the Fuck You Want to Public License), see LICENSE for details.