Mojolicious-Plugin-Fondation-CSRF
view release on metacpan or search on metacpan
# NAME
Mojolicious::Plugin::Fondation::CSRF - CSRF protection plugin for Fondation — route condition, OpenAPI integration, JS injection
# VERSION
version 0.02
# SYNOPSIS
# In myapp.conf
plugin 'Fondation' => {
dependencies => [
'Fondation::SessionStore', # sessions required for CSRF tokens
'Fondation::CSRF',
],
};
# Per-route opt-in (when auto_protect is disabled):
$r->post('/secure-action')->requires('fondation.csrf')->to('mycontroller#action');
# With exemptions:
'Fondation::CSRF' => {
auto_protect => 1,
exemptions => [qr{^/webhook/}, qr{^/api/public/}],
},
# DESCRIPTION
`Mojolicious::Plugin::Fondation::CSRF` provides Cross-Site Request Forgery
protection for Fondation applications. It uses Mojolicious' built-in CSRF
token mechanism (stored in session, validated via ["csrf\_protect" in Validation](https://metacpan.org/pod/Validation#csrf_protect)).
Three protection layers, all using the same underlying Mojo validation:
- 1. Route condition `fondation.csrf` — explicit opt-in on any route
- 2. OpenAPI auto-protection — POST/PUT/PATCH/DELETE routes generated
by [Fondation::OpenAPI](https://metacpan.org/pod/Fondation%3A%3AOpenAPI) automatically get `requires('fondation.csrf')`
- 3. `around_dispatch` blanket protection — all mutating requests
(POST/PUT/PATCH/DELETE) are checked unless the path matches an exemption
Token transmission works two ways, both handled automatically by Mojo:
- Form field `csrf_token` — standard HTML forms via ["csrf\_field" in TagHelpers](https://metacpan.org/pod/TagHelpers#csrf_field)
- Header `X-CSRF-Token` — AJAX requests (the plugin provides a JS zone
that reads the CSRF meta tag and patches `fetch` and `XMLHttpRequest`)
# CONFIGURATION
- auto\_protect
Enable/disable the `around_dispatch` blanket protection.
Default: `1` (enabled). Set to `0` to use only explicit route conditions.
- exemptions
Arrayref of regex patterns. Paths matching any pattern are skipped by
`around_dispatch`. Useful for webhooks, public API endpoints, etc.
Default: `[]` (no exemptions).
# DEPENDENCIES
[Mojolicious::Plugin::Fondation](https://metacpan.org/pod/Mojolicious%3A%3APlugin%3A%3AFondation).
Sessions must be enabled ([Fondation::SessionStore](https://metacpan.org/pod/Fondation%3A%3ASessionStore) or Mojolicious' default
signed cookies). The CSRF token lives in `$c->session->{csrf_token}`.
# STATIC JS FILE
The plugin ships `share/public/js/csrf.js` — a standalone script that
reads the CSRF token from `<meta name="csrf-token">` and auto-injects
it as `X-CSRF-Token` header on all `fetch` and `XMLHttpRequest`
POST/PUT/PATCH/DELETE calls.
Add it to your assetpack.def:
< js/csrf.js
Or include it directly in your layout:
<script src="/js/csrf.js"></script>
The meta tag must be present in the page. [Fondation::Layout-Bootstrap](https://metacpan.org/pod/Fondation%3A%3ALayout-Bootstrap)
provides it by default:
<meta name="csrf-token" content="<%= csrf_token %>">
# END-TO-END FLOW
When the CSRF plugin is loaded alongside the standard Fondation stack
(Layout-Bootstrap, Asset, OpenAPI, Auth), protection works automatically:
- 1. Layout-Bootstrap injects `<meta name="csrf-token">` in `<head>`.
- 2. `csrf.js` (loaded via AssetPack bundle or `<script src>`) patches
`fetch` and `XMLHttpRequest` to inject `X-CSRF-Token` on all mutating AJAX calls.
- 3. HTML forms (login, etc.) include `<%= csrf_field %>` to embed
the token as a hidden field.
- 4. OpenAPI routes (POST/PUT/PATCH/DELETE) automatically get
`requires('fondation.csrf')` via the `openapi_routes_added` hook.
- 5. HTML POST routes are protected by `around_dispatch` when
`auto_protect` is enabled (default), or by explicit `requires('fondation.csrf')`.
- 6. Mojo's `csrf_protect` validates the token from form field or
`X-CSRF-Token` header against the session token.
# HOW TOKEN VALIDATION WORKS
The route condition and `around_dispatch` both delegate to Mojo's
`csrf_protect` validation:
- 1. Mojo generates a unique token on first session access
- 2. Token is stored in `$c->session->{csrf_token}`
- 3. Client sends the token back (form field or `X-CSRF-Token` header)
- 4. `csrf_protect` compares the submitted token with the session token
- 5. Mismatch → validation error `csrf_token` → 403
# SEE ALSO
[Mojolicious::Plugin::Fondation](https://metacpan.org/pod/Mojolicious%3A%3APlugin%3A%3AFondation),
[Mojolicious::Plugin::Fondation::OpenAPI](https://metacpan.org/pod/Mojolicious%3A%3APlugin%3A%3AFondation%3A%3AOpenAPI),
[Mojolicious::Guides::Routing](https://metacpan.org/pod/Mojolicious%3A%3AGuides%3A%3ARouting),
[Mojolicious::Validator::Validation](https://metacpan.org/pod/Mojolicious%3A%3AValidator%3A%3AValidation)
# AUTHOR
Daniel Brosseau <dab@cpan.org>
# COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Daniel Brosseau.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
( run in 0.790 second using v1.01-cache-2.11-cpan-ad19def0cd9 )