Csrf class

CSRF (Cross-Site Request Forgery) Protection middleware.

Protects against CSRF attacks by validating the Origin and Sec-Fetch-Site headers for unsafe HTTP methods (POST, PUT, DELETE, PATCH).

CSRF attacks occur when a malicious site tricks a user's browser into making unauthorized requests to your site. This middleware prevents such attacks by checking that requests originate from trusted sources.

How it works:

1. Safe methods (GET, HEAD, OPTIONS) are allowed without validation
2. For unsafe methods (POST, PUT, DELETE, PATCH):
   • Validates Origin header against allowed origins
   • Falls back to Sec-Fetch-Site header validation
   • Rejects requests missing both headers
3. Only validates requests with form-like Content-Types to avoid blocking legitimate API requests (JSON, XML, etc.)

Security notes:

• Always use HTTPS in production
• This is a defense-in-depth measure, not a complete CSRF solution
• For APIs, consider using token-based CSRF protection
• Modern browsers provide additional CSRF protection via SameSite cookies

Example usage:

// Allow requests from a single origin
app.use(Csrf.origin('https://example.com'));

// Allow requests from multiple origins
app.use(Csrf.origins([
  'https://example.com',
  'https://www.example.com',
]));

// Custom origin validation
app.use(Csrf.originValidator((origin, ctx) {
  return origin.endsWith('.example.com');
}));

// Validate using Sec-Fetch-Site header
app.use(Csrf.secFetchSite('same-origin'));

// Allow same-origin and same-site
app.use(Csrf.secFetchSites(['same-origin', 'same-site']));

// Custom error message
app.use(Csrf.origin(
  'https://example.com',
  errorMessage: 'Invalid request origin',
));

Implemented types

• Middleware

Constructors

Csrf.origin(String origin, {String errorMessage = 'Potential CSRF attack detected'})

Creates a CSRF middleware that validates against a single origin.

factory

Csrf.origins(List<String> origins, {String errorMessage = 'Potential CSRF attack detected'})

Creates a CSRF middleware that validates against multiple origins.

factory

Csrf.originValidator(OriginValidator validator, {String errorMessage = 'Potential CSRF attack detected'})

Creates a CSRF middleware with a custom origin validator function.

factory

Csrf.secFetchSite(String secFetchSite, {String errorMessage = 'Potential CSRF attack detected'})

Creates a CSRF middleware that validates against a single Sec-Fetch-Site value.

factory

Csrf.secFetchSites(List<String> secFetchSites, {String errorMessage = 'Potential CSRF attack detected'})

Creates a CSRF middleware that validates against multiple Sec-Fetch-Site values.

factory

Csrf.secFetchSiteValidator(SecFetchSiteValidator validator, {String errorMessage = 'Potential CSRF attack detected'})

Creates a CSRF middleware with a custom Sec-Fetch-Site validator function.

factory

Properties

errorMessage → String

Custom error message to return when CSRF validation fails.

final

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

handle(Context ctx, NextFunction next) → Future<void>

override

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited