Skip to content

Latest commit

 

History

History
414 lines (289 loc) · 8.67 KB

README.md

File metadata and controls

414 lines (289 loc) · 8.67 KB
Raw

Kitty

Kitty is a collection of utilities for SvelteKit. It includes libraries and handlers for developing secure frontend apps.

Kitty features encrypted server-side sessions, and provides mitigations against CSRF attacks for forms submitted to the server.

Installing

  1. Install via NPM:

    npm install @grottopress/kitty

  2. Set compilerOptions.moduleResolution to bundler, node16, or nodenext in tsconfig.json:

    {
  "compilerOptions": {
    "moduleResolution": "bundler",
  }
}

    This prevents the following error:

    Cannot find module '@grottopress/kitty' or its corresponding type declarations

    See https://kit.svelte.dev/docs/packaging#typescript.

  3. Set up vite.config.js as follows:

    // ->> vite.config.js

// ...

/** @type {import('vite').UserConfig} */
const config = {
  // ...
  optimizeDeps: {
    exclude: ['@grottopress/kitty'],
  },
  ssr: {
    noExternal: ['@grottopress/kitty'],
  },
  // ...
}

export default config

Using

Handlers

Kitty provides the following handlers:

  • decryptSession: Decrypts session retrieved from the Cookie request header
  • disableCache: Sets Cache-Control and Expires headers to disable caching app-wide
  • encryptSession: Encrypts session and sends it via the Set-Cookie response header
  • filterRequestMethods: Forbids requests methods not listed in the ALLOWED_REQUEST_METHODS env var
  • verifyCsrfToken: Generates and verifies CSRF tokens for requests that require them

The src/hooks.server.ts file should look similar to this:

// ->> src/hooks.server.ts

// ...

import { sequence } from '@sveltejs/kit/hooks'
import {
  decryptSession,
  disableCache,
  encryptSession,
  filterRequestMethods,
  verifyCsrfToken
} from '@grottopress/kitty/server'

export const handle = sequence(
  decryptSession,
  filterRequestMethods,
  verifyCsrfToken,
  disableCache,
  encryptSession
)

// ...

Add the following to the .env file:

# ->> .env

# ...

# Client
#

# Server
#
ALLOWED_REQUEST_METHODS=DELETE,GET,HEAD,PATCH,POST
SECRET_KEY=J9oyuTDuGSQhwE3lOutjUgXe4yfpWQtI # 32 bytes/chars
SESSION_KEY=_my-app-session

# ...

Update the file with your own details. Use a cryptographically-secure value for the secret key. You may run tr -cd '[:alnum:]' < /dev/random | fold -w32 | head -n1 to generate a key.

Remember to set secure permissions for this file: chmod 0600 .env.

Add types to src/app.d.ts:

declare namespace App {
  // ...

  interface Locals {
    session: Session
    // ...
  }

  interface PageData {
    csrfHeaderKey?: string
    csrfParamKey?: string
    csrfToken?: string
    // ...
  }

  interface Session {
    csrfHeaderKey?: string
    csrfParamKey?: string
    csrfToken?: string
    // ...
  }

  // ...
}

// ...

Session

Kitty features encrypted server-side sessions. Any value stored in the event.locals.session object is encrypted and persisted as cookies on the client via the Set-Cookie response header.

Sessions can be made available client-side via the session store by defining .load() in src/routes/+layout.server.ts as follows:

// ->> src/routes/+layout.server.ts

// ...

import type { ServerLoad } from '@sveltejs/kit'

export const load: ServerLoad = async ({ locals }) => {
  const { csrfHeaderKey, csrfParamKey, csrfToken } = locals.session

  return { csrfHeaderKey, csrfParamKey, csrfToken }
}

// ...
// ->> src/routes/+layout.ts

// ...

import type { Load } from '@sveltejs/kit'

export const load: Load = async ({ data }) => {
  const csrfHeaderKey = data?.csrfHeaderKey
  const csrfParamKey = data?.csrfParamKey
  const csrfToken = data?.csrfToken

  return { csrfHeaderKey, csrfParamKey, csrfToken }
}

// ...

This can then be accessed in routes (eg: data.csrfToken), or via the page store in components (eg: $page.data.csrfToken).

CSRF

Kitty provides support for generating and verifying CSRF tokens for forms submitted to the server, either via JSON or as form data.

CSRF mitigations are enforced for all requests except those with the GET, HEAD, OPTIONS, and TRACE methods.

Examples:

# ->> .env

# ...

# Skip CSRF protection for these routes (comma-separated `event.route.id`s).
# Adding a route will include all its children.
CSRF_SKIP_ROUTES=/about/team,/blog/[slug]

# ...

  • JSON:

    // src/routes/some-path/+page.ts

// ...

import type { Load } from '@sveltejs/kit'

export const load: Load = async ({ fetch }) => {
  return { fetch }
}

// ...
    <!-- src/routes/some-path/+page.svelte -->

<script lang="ts">
  interface Props {
    data: App.PageData
  }

  let { data }: Props = $props()

  let city = $state('')
  let response: Response | undefined = $state()

  const onSubmit = async (event: Event) => {
    event.preventDefault()

    if (!data.csrfHeaderKey || !data.csrfToken) return

    const headers = new Headers
    headers.set('Content-Type', 'application/json')
    headers.set(data.csrfHeaderKey, data.csrfToken)

    response = await data.fetch('/some-endpoint', {
      method: 'POST',
      headers,
      body: JSON.stringify({ city })
    })
  }
</script>

<h1>City</h1>

<!-- ... -->

<form onsubmit={onSubmit}>
  <input type="text" name="city" bind:value={city} />
  <button type="submit">Submit</button>
</form>

<!-- ... -->

  • Form data:

    <script lang="ts">
  interface Props {
    data: App.PageData
  }

  let { data }: Props = $props()

  let city = $state('')

  // ...
</script>

<h1>City</h1>

<!-- ... -->

<form method="POST" action="/some-endpoint">
  <input type="hidden" name={data.csrfParamKey} value={data.csrfToken} />
  <input type="text" name="city" bind:value={city} />
  <button type="submit">Submit</button>
</form>

<!-- ... -->

Components

The following components are available:

  • Connection

    <script lang="ts">
  import { Connection } from '@grottopress/kitty'
</script>

<Connection slowAfterMs={6000}>
  {#snippet offline()}
    <aside class="connection offline">
      <p>You are offline</p>
    </aside>
  {/snippet}

  {#snippet slow()}
    <aside class="connection slow">
      <p>Check your internet connection</p>
    </aside>
  {/snippet}

  {#snippet online()}
    <aside class="connection online">
      <p>Hurray!!!</p>
    </aside>
  {/snippet}
</Connection>

    The slowAfterMs prop sets the connection status to slow if a page is not loaded after the given period in milliseconds.

  • ToggleButton

    <script lang="ts">
  import { ToggleButton } from '@grottopress/kitty'

  let menu: HTMLElement | undefined = $state()
  let showMenu = $state(false)
</script>

<div>
  <ToggleButton bind:open={showMenu} target={menu} clickOutside>
    &equiv; Menu
  </ToggleButton>

  {#if showMenu}
    <nav bind:this={menu}>
      <a href="/link/a">Link A</a>
      <a href="/link/b">Link B</a>
      <a href="/link/c">Link C</a>
    </nav>
  {/if}
</div>

    The clickOutside prop, if true, enables closing a menu by clicking anywhere outside the button and its target.

Actions

Kitty comes with the following actions for use in components:

  • clickOutside

    <script lang="ts">
  import { clickOutside } from '@grottopress/kitty'

  interface Props {
    open: boolean
  }

  let { open }: Props = $props()

  const toggle = () => {
    open = !open
  }

  const close = () => {
    open = false
  }
</script>

<button type="button" use:clickOutside={close} onclick={toggle}>
  <slot />
</button>

Helpers

The following helpers are available:

  • .isJson(context: Request | Response): boolean

    import { isJson } from '@grottopress/kitty'

isJson(requestOrResponseObject)

    .isJson() checks if the given request or response is JSON, based on its Content-Type header.

Developing

After cloning this repository, copy sample.env to .env, and run npm install. You may start the development server with npm run dev, or run tests with npm run test.

Contributing

  1. Fork it
  2. Switch to the master branch: git checkout master
  3. Create your feature branch: git checkout -b my-new-feature
  4. Make your changes, updating changelog and documentation as appropriate.
  5. Commit your changes: git commit
  6. Push to the branch: git push origin my-new-feature
  7. Submit a new Pull Request against the GrottoPress:master branch.