SvelteKit

This is the documentation for Edge-CSRF's SvelteKit integration.

Quickstart

First, add the integration library as a dependency to your app:

1npm install @edge-csrf/sveltekit
2# or
3pnpm add @edge-csrf/sveltekit
4# or
5yarn add @edge-csrf/sveltekit

Next, create a server-side hooks file (hooks.server.ts) for your project and add the Edge-CSRF handle:

1// src/hooks.server.ts
2
3import { createCsrfHandle } from '@edge-csrf/sveltekit';
4
5// initalize csrf protection handle
6const csrfHandle = createCsrfHandle({
7  cookie: {
8    secure: process.env.NODE_ENV === 'production',
9  },
10});
11
12export const handle = csrfHandle;

Now, all HTTP submission requests (e.g. POST, PUT, DELETE, PATCH) will be rejected if they do not include a valid CSRF token. To add the CSRF token to your forms, you can fetch it from the event's locals data object server-side. For example:

1// src/routes/+page.server.ts
2
3export async function load({ locals }) {
4  return {
5    csrfToken: locals.csrfToken,
6  };
7}
8
9export const actions = {
10  default: async () => {
11    return { success: true };
12  },
13};

1<!-- src/routes/+page.svelte -->
2
3<script lang="ts">
4  export let data;
5
6  export let form;
7</script>
8
9{#if form?.success}
10<span>success</span>
11{:else}
12<form method="post">
13  <input type="hidden" value={data.csrfToken}>
14  <input type="text" name="my-input">
15  <input type="submit">
16</form>
17{/if}

Finally, to make typescript aware of the new locals attributes you can add Edge-CSRF types to your app's types:

1// src/app.d.ts
2
3import type { CsrfLocals } from '@edge-csrf/sveltekit';
4
5declare global {
6  namespace App {
7    // ...
8    interface Locals extends CsrfLocals {}
9    // ...
10  }
11}
12
13export {};

Examples

Here are some examples in this repository:

Adapter	Implementation
vercel	HTML form
cloudflare	HTML form

Lower-level implementations

If you want lower-level control over the response or which routes CSRF protection will be applied to you can use the createCsrfProtect() method to create a function that you can use inside your own custom handle:

1// src/hooks.server.ts
2
3import type { Handle } from '@sveltejs/kit';
4import { CsrfError, createCsrfProtect } from '@edge-csrf/sveltekit';
5
6// initalize csrf protection method
7const csrfProtect = createCsrfProtect({
8  cookie: {
9    secure: process.env.NODE_ENV === 'production',
10  },
11});
12
13// SvelteKit handle
14export const handle: Handle = async ({ event, resolve }) => {
15  try {
16    await csrfProtect(event);
17  } catch (err) {
18    if (err instanceof CsrfError) return new Response('invalid csrf token', { status: 403 });
19    throw err;
20  }
21    
22  return resolve(event);
23};

Configuration

1// default config
2
3{
4  cookie: {
5    name: '_csrfSecret',
6    path: '/',
7    maxAge: undefined,
8    domain: '',
9    secure: true,
10    httpOnly: true,
11    sameSite: 'strict'
12  },
13  excludePathPrefixes: [],
14  ignoreMethods: ['GET', 'HEAD', 'OPTIONS'],
15  saltByteLength: 8,
16  secretByteLength: 18,
17  token: {
18    fieldName: 'csrf_token',
19    value: undefined
20  }
21}

API

The following are named exports in the the @edge-csrf/sveltekit module:

Types

SveltekitCsrfProtect - A function that implements CSRF protection for SvelteKit request events

  * @param {RequestEvent} event - The SvelteKit request event instance
  * @returns {Promise<void>} - The function completed successfully
  * @throws {CsrfError} - The function encountered a CSRF error

Classes

CsrfError - A class that inherits from Error and represents CSRF errors

Methods

createCsrfHandle([, options]) - Create a new SvelteKit handle to be used in hooks.server.ts

  * @param {object} [options] - The configuration options
  * @returns {Handle} - The handle

createCsrfProtect([, options]) - Create a lower-level function that can be used inside a SvelteKit handle
                                 to implement CSRF protection for requests

  * @param {object} [options] - The configuration options
  * @returns {SveltekitCsrfProtect} - The CSRF protection function