Coraza for Node.js

Returns a RequestHandler. Takes a pre-built WAF (or WAFPool) so construction happens once at boot and the middleware stays sync-to-mount.

function coraza(options: CorazaExpressOptions): RequestHandler

interface CorazaExpressOptions {
  /** Built via createWAF / createWAFPool. */
  waf: WAF | WAFPool
  /** Custom block response. Default: 403 text/plain with rule id. */
  onBlock?: (i: Interruption, req: Request, res: Response) => void
  /** Run response-phase rules too. Default false. */
  inspectResponse?: boolean
  /** Unified bypass spec — extensions, routes, methods, body cutoff, header
   *  equality, custom predicate. See "Skipping the WAF" below. */
  ignore?: IgnoreSpec | false
  /** WAF error behavior. Default 'block' — fail-closed. */
  onWAFError?: 'allow' | 'block'
}

Example — custom block handler + pool

import { createWAFPool } from '@coraza/core'
import { coraza } from '@coraza/express'

const waf = await createWAFPool({
  rules: recommended(),
  mode: 'block',
  size: 8,
})

app.use(coraza({
  waf,
  ignore: { routes: ['/health*', '/metrics*'] },
  onBlock(it, req, res) {
    metrics.inc('waf.blocked', { ruleId: it.ruleId })
    res.status(it.status || 403).json({
      error: 'forbidden',
      ruleId: it.ruleId,
      traceId: req.headers['x-trace-id'],
    })
  },
}))

Skipping the WAF — ignore

Pass ignore: to declare which requests bypass Coraza. Every field is optional; combine freely. Identical shape across every adapter.

Verdicts: false (inspect), true (skip everything), 'skip-body' (inspect URL + headers, skip the body phase). When both declarative rules and match produce a verdict, most-restrictive wins: false > 'skip-body' > true.

The legacy skip: option is soft-deprecated for one preview, mapped to ignore: at construction with a one-shot warning per process, and removed at stable 0.1.

Encapsulatable — register inside a scope to protect a subset of routes. Forwards block logs through request.log (Pino by default).

const coraza: FastifyPluginAsync<CorazaFastifyOptions>

interface CorazaFastifyOptions {
  waf: WAF | WAFPool
  onBlock?: (i: Interruption, req: FastifyRequest, reply: FastifyReply) => void | Promise<void>
  inspectResponse?: boolean
  ignore?: IgnoreSpec | false
  onWAFError?: 'allow' | 'block'
}

Example — scoped to /api

import Fastify from 'fastify'
import { createWAF } from '@coraza/core'
import { coraza } from '@coraza/fastify'

const app = Fastify({ logger: true })
const waf = await createWAF({ rules: recommended(), mode: 'block' })

app.register(async (api) => {
  await api.register(coraza, {
    waf,
    onBlock(it, req, reply) {
      req.log.warn({ it }, 'waf_block')
      reply.code(it.status || 403).send({ error: 'forbidden' })
    },
  })
}, { prefix: '/api' })

Returns a Next middleware export. Accepts either a built WAF / WAFPool or a promise of one — useful for deferring WASM compile in CJS setups without top-level await.

function coraza(options: CorazaNextOptions): NextMiddleware

interface CorazaNextOptions {
  waf: WAF | WAFPool | Promise<WAF | WAFPool>
  onBlock?: (i: Interruption, req: NextRequest) => Response
  ignore?: IgnoreSpec | false
  onWAFError?: 'allow' | 'block'
}

Example — Next 16 proxy.ts

import { createWAF } from '@coraza/core'
import { coraza } from '@coraza/next'
import { recommended } from '@coraza/coreruleset'
import { NextResponse } from 'next/server'

const waf = createWAF({ rules: recommended(), mode: 'block' })

export const proxy = coraza({
  waf,
  onBlock(it) {
    return NextResponse.json(
      { error: 'forbidden', ruleId: it.ruleId },
      { status: it.status || 403 },
    )
  },
})

// Next 16's proxy.ts defaults to the Node.js runtime — `runtime: 'nodejs'`
// is rejected here. Use this exact shape on Next 15 in middleware.ts and
// add `runtime: 'nodejs'` to the config object.
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

Live examples: examples/next15-app (Next 15 + middleware.ts) and examples/next16-app (Next 16 + proxy.ts).

Import into your root module. Registers CorazaGuard as APP_GUARD by default so every route is protected; opt out with globalGuard: false and apply @UseGuards(CorazaGuard) selectively.

class CorazaModule {
  static forRoot(options: CorazaNestOptions): DynamicModule
  static forRootAsync(options: CorazaNestAsyncOptions): DynamicModule
}

interface CorazaNestOptions extends WAFConfig {
  globalGuard?: boolean           // default true
  ignore?: IgnoreSpec | false
  onBlock?: (i: Interruption) => HttpException
  onWAFError?: 'allow' | 'block'
}

Example — opt-in per route

import { Controller, Get, UseGuards } from '@nestjs/common'
import { CorazaGuard } from '@coraza/nestjs'

@Controller('billing')
export class BillingController {
  @UseGuards(CorazaGuard)
  @Get('invoice')
  invoice() {
    return { ok: true }
  }
}