Open History to see the last commit
1import { createIsomorphicFn } from '@tanstack/start-fn-stubs'
2import { isPromise } from '@tanstack/router-core'
3import { createMiddleware } from './createMiddleware'
4import type {
5 RequestMiddlewareAfterServer,
6 RequestServerOptions,
7} from './createMiddleware'
8import type { Register } from '@tanstack/router-core'
9β
10export const csrfSymbol = Symbol.for('tanstack-start:csrf-middleware')
11β
12export type CsrfSecFetchSite =
13 | 'same-origin'
14 | 'same-site'
15 | 'cross-site'
16 | 'none'
17β
18export type CsrfMatcher<TValue, TRegister = Register, TMiddlewares = unknown> =
19 | TValue
20 | Array<TValue>
21 | ((
22 value: TValue | (string & {}),
23 ctx: RequestServerOptions<TRegister, TMiddlewares>,
24 ) => boolean | Promise<boolean>)
25β
26export interface CsrfMiddlewareOptions<
27 TRegister = Register,
28 TMiddlewares = unknown,
29> {
30 /**
31 * Return `true` to validate this request, or `false` to skip validation.
32 *
33 * @default undefined, which validates every request handled by this middleware.
34 */
35 filter?: (
36 ctx: RequestServerOptions<TRegister, TMiddlewares>,
37 ) => boolean | Promise<boolean>
38 /**
39 * Allowed Origin values. Defaults to the trusted request origin.
40 */
41 origin?: CsrfMatcher<string, TRegister, TMiddlewares>
42 /**
43 * Allowed Sec-Fetch-Site values.
44 *
45 * @default 'same-origin'
46 */
47 secFetchSite?: CsrfMatcher<CsrfSecFetchSite, TRegister, TMiddlewares>
48 /**
49 * Whether to use Referer as a fallback when Sec-Fetch-Site and Origin are absent.
50 *
51 * @default true
52 */
53 referer?:
54 | boolean
55 | ((
56 referer: string,
57 ctx: RequestServerOptions<TRegister, TMiddlewares>,
58 ) => boolean | Promise<boolean>)
59 /**
60 * Allow requests when Sec-Fetch-Site, Origin, and Referer are all missing.
61 *
62 * @default false
63 */
64 allowRequestsWithoutOriginCheck?: boolean
65 /**
66 * Optional response returned when CSRF validation fails.
67 *
68 * @default new Response('Forbidden', { status: 403 })
69 */
70 failureResponse?:
71 | Response
72 | ((
73 ctx: RequestServerOptions<TRegister, TMiddlewares>,
74 ) => Response | Promise<Response>)
75}
76β
77type CreateCsrfMiddleware = <TRegister, TMiddlewares>(
78 opts?: CsrfMiddlewareOptions<TRegister, TMiddlewares>,
79) => RequestMiddlewareAfterServer<{}, undefined, undefined>
80β
81const innerCreateCsrfMiddleware: CreateCsrfMiddleware = (opts = {}) => {
82 const continueRequest = (
83 result: boolean | undefined,
84 ctx: RequestServerOptions<any, any>,
85 ) => {
86 return isValidationResultAllowed(result, opts)
87 ? ctx.next()
88 : getFailureResponse(opts, ctx)
89 }
90β
91 const validateRequest = (ctx: RequestServerOptions<any, any>) => {
92 const result = validateCsrfRequest(opts, ctx)
93 if (isPromise(result)) {
94 return result.then((result) => continueRequest(result, ctx))
95 }
96 return continueRequest(result, ctx)
97 }
98β
99 // Synchronous checks can pass through next() without another promise chain.
100 const middleware = createMiddleware().server((ctx) => {
101 const csrfCtx = ctx as RequestServerOptions<any, any>
102 try {
103 if (opts.filter) {
104 const shouldValidate = opts.filter(csrfCtx)
105 if (isPromise(shouldValidate)) {
106 return shouldValidate.then((shouldValidate) =>
107 shouldValidate ? validateRequest(csrfCtx) : ctx.next(),
108 )
109 }
110 if (!shouldValidate) {
111 return ctx.next()
112 }
113 }
114 return validateRequest(csrfCtx)
115 } catch (error) {
116 return Promise.reject(error)
117 }
118 })
119β
120 if (process.env.NODE_ENV !== 'production') {
121 Object.defineProperty(middleware, csrfSymbol, { value: true })
122 }
123β
124 return middleware
125}
126β
127export const createCsrfMiddleware: CreateCsrfMiddleware =
128 createIsomorphicFn().server(innerCreateCsrfMiddleware) as CreateCsrfMiddleware
129β
130export async function isCsrfRequestAllowed<TRegister, TMiddlewares>(
131 opts: CsrfMiddlewareOptions<TRegister, TMiddlewares>,
132 ctx: RequestServerOptions<TRegister, TMiddlewares>,
133): Promise<boolean> {
134 return isValidationResultAllowed(await validateCsrfRequest(opts, ctx), opts)
135}
136β
137function isValidationResultAllowed<TRegister, TMiddlewares>(
138 result: boolean | undefined,
139 opts: CsrfMiddlewareOptions<TRegister, TMiddlewares>,
140): boolean {
141 return (
142 result === true ||
143 (result === undefined && opts.allowRequestsWithoutOriginCheck === true)
144 )
145}
146β
147export async function getCsrfRequestValidationResult<TRegister, TMiddlewares>(
148 opts: CsrfMiddlewareOptions<TRegister, TMiddlewares>,
149 ctx: RequestServerOptions<TRegister, TMiddlewares>,
150): Promise<boolean | undefined> {
151 return validateCsrfRequest(opts, ctx)
152}
153β
154function validateCsrfRequest<TRegister, TMiddlewares>(
155 opts: CsrfMiddlewareOptions<TRegister, TMiddlewares>,
156 ctx: RequestServerOptions<TRegister, TMiddlewares>,
157): boolean | undefined | Promise<boolean> {
158 const fetchSite = ctx.request.headers.get('Sec-Fetch-Site')
159 if (fetchSite !== null) {
160 return matchValue(opts.secFetchSite ?? 'same-origin', fetchSite, ctx)
161 }
162β
163 const origin = ctx.request.headers.get('Origin')
164 if (origin !== null) {
165 if (opts.origin) {
166 return matchValue(opts.origin, origin, ctx)
167 }
168β
169 return origin === new URL(ctx.request.url).origin
170 }
171β
172 const referer = ctx.request.headers.get('Referer')
173 if (referer === null || opts.referer === false) {
174 return undefined
175 }
176β
177 if (typeof opts.referer === 'function') {
178 return opts.referer(referer, ctx)
179 }
180β
181 if (opts.origin) {
182 const refererOrigin = getOriginFromUrl(referer)
183 return (
184 refererOrigin !== undefined && matchValue(opts.origin, refererOrigin, ctx)
185 )
186 }
187β
188 return isRefererSameOrigin(referer, new URL(ctx.request.url).origin)
189}
190β
191function matchValue<TValue extends string, TRegister, TMiddlewares>(
192 matcher: CsrfMatcher<TValue, TRegister, TMiddlewares>,
193 value: string,
194 ctx: RequestServerOptions<TRegister, TMiddlewares>,
195): boolean | Promise<boolean> {
196 if (typeof matcher === 'function') {
197 return matcher(value, ctx)
198 }
199β
200 if (Array.isArray(matcher)) {
201 // typescript is dumb for array.includes()
202 return matcher.includes(value as TValue)
203 }
204β
205 return value === matcher
206}
207β
208function getOriginFromUrl(url: string): string | undefined {
209 try {
210 return new URL(url).origin
211 } catch {
212 return undefined
213 }
214}
215β
216function isRefererSameOrigin(referer: string, requestOrigin: string): boolean {
217 if (referer === requestOrigin) {
218 return true
219 }
220 if (!referer.startsWith(requestOrigin)) {
221 return false
222 }
223 if (referer.length === requestOrigin.length) {
224 return true
225 }
226 const code = referer.charCodeAt(requestOrigin.length)
227 return code === 47 /* '/' */ || code === 63 /* '?' */ || code === 35 /* '#' */
228}
229β
230function getFailureResponse<TRegister, TMiddlewares>(
231 opts: CsrfMiddlewareOptions<TRegister, TMiddlewares>,
232 ctx: RequestServerOptions<TRegister, TMiddlewares>,
233): Response | Promise<Response> {
234 if (typeof opts.failureResponse === 'function') {
235 return opts.failureResponse(ctx)
236 }
237β
238 return (
239 opts.failureResponse?.clone() ?? new Response('Forbidden', { status: 403 })
240 )
241}