RFC: CSRF protection

[pilcrowonpaper]

Summary

Simplify LuciaRequest and LuciaRequestContext interface, which would allow us to simplify existing middleware.

Background

LuciaRequest was built with the standard Request in mind, which provides access to the request url, method, and headers. However, Node's IncomingMessage does not provide the full url, and Next.js App Router does not provide the request url or method in certain context.

CSRF protection

Where:

• URL is LuciaRequestContext.request.url
• HOST is Configuration.csrfProtection.host
• HOST_HEADER is Configuration.csrfProtection.hostHeader (default: "Host")
• ALLOWED_SUBDOMAINS is Configuration.csrfProtection.allowedSubdomains

CSRF protection will be handled in the following order:

1. If request method is "GET", the request is valid
2. If Origin header is not defined, the request is invalid
3. If HOST is defined:
   1. If the host of the Origin header matches HOST, the request is valid
   2. If not, the request is invalid
4. If URL is defined:
   1. If the host of the Origin header matches the host of URL, the request is valid
   2. If not, the request is invalid
5. If the host of the Origin header matches HOST_HEADER header, the request is valid
6. If not, the request is invalid

ALLOWED_SUBDOMAINS will be taken into account when determining if a host matches another.

API Design

LuciaRequest.headers now take a standard Headers. As such, this interface fully compatible with the standard Request. LuciaRequest.storedSessionCookie will be moved to LuciaRequestContext.sessionCookie.

interface LuciaRequest {
	method: string;
	headers: Headers; // now
	url?: string;
    storedSessionCookie?: string | null; // remove: v3
}

interface LuciaRequestContext {
	sessionCookie?: string | null;
	request: LuciaRequest;
	setCookie: (cookie: Cookie) => void;
}

The new CSRF protection configuration will add host and hostHeader options.

interface Configuration {
    csrfProtection: boolean | {
        host?: string, // can be a host or origin
        hostHeader?: string // default "Host"
        allowedSubdomains?: string[]
    }
}

Considerations

While the new LuciaRequest will replace the old one in v3, both versions will be deemed valid for v2 to not introduce breaking changes.

Deprecation

• AuthRequest.validateRequestOrigin() (remove v3)

[pilcrowonpaper]

See PR #1096