From f13aef7fe740200677cb1f19b6a84bcdb69a46a5 Mon Sep 17 00:00:00 2001 From: Ben McCann <322311+benmccann@users.noreply.github.com> Date: Fri, 25 Oct 2024 11:37:02 -0700 Subject: [PATCH] docs: auth guide (#12810) Co-authored-by: Tee Ming --- documentation/docs/30-advanced/20-hooks.md | 6 ++++- .../docs/40-best-practices/03-auth.md | 23 +++++++++++++++++++ packages/kit/src/exports/public.d.ts | 2 +- packages/kit/src/types/ambient.d.ts | 2 +- packages/kit/types/index.d.ts | 4 ++-- 5 files changed, 32 insertions(+), 5 deletions(-) create mode 100644 documentation/docs/40-best-practices/03-auth.md diff --git a/documentation/docs/30-advanced/20-hooks.md b/documentation/docs/30-advanced/20-hooks.md index 74d4c815d835..6decc1cbf463 100644 --- a/documentation/docs/30-advanced/20-hooks.md +++ b/documentation/docs/30-advanced/20-hooks.md @@ -37,7 +37,11 @@ export async function handle({ event, resolve }) { > [!NOTE] Requests for static assets — which includes pages that were already prerendered — are _not_ handled by SvelteKit. -If unimplemented, defaults to `({ event, resolve }) => resolve(event)`. To add custom data to the request, which is passed to handlers in `+server.js` and server `load` functions, populate the `event.locals` object, as shown below. +If unimplemented, defaults to `({ event, resolve }) => resolve(event)`. + +### locals + +To add custom data to the request, which is passed to handlers in `+server.js` and server `load` functions, populate the `event.locals` object, as shown below. ```js /// file: src/hooks.server.js diff --git a/documentation/docs/40-best-practices/03-auth.md b/documentation/docs/40-best-practices/03-auth.md new file mode 100644 index 000000000000..e9ca3384780c --- /dev/null +++ b/documentation/docs/40-best-practices/03-auth.md @@ -0,0 +1,23 @@ +--- +title: Auth +--- + +Auth refers to authentication and authorization, which are common needs when building a web application. Authentication means verifying that the user is who they say they are based on their provided credentials. Authorization means determining which actions they are allowed to take. + +## Sessions vs tokens + +After the user has provided their credentials such as a username and password, we want to allow them to use the application without needing to provide their credentials again for future requests. Users are commonly authenticated on subsequent requests with either a session identifier or signed token such as a JSON Web Token (JWT). + +Session IDs are most commonly stored in a database. They can be immediately revoked, but require a database query to be made on each request. + +In contrast, JWT generally are not checked against a datastore, which means they cannot be immediately revoked. The advantage of this method is improved latency and reduced load on your datastore. + +## Integration points + +Auth [cookies](types#public-types-cookies) can be checked inside [server hooks](hooks#server-hooks). If a user is found matching the provided credentials, the user information can be stored in [`locals`](hooks#server-hooks-locals). + +## Guides + +[Lucia](https://lucia-next.pages.dev/) is a reference for session-based web app auth. It contains example code snippets and projects for implementing session-based auth within SvelteKit and other JS projects. You can add code which follows the Lucia guide to your project with `npx sv create` when creating a new project or `npx sv add lucia` for an existing project. + +An auth system is tightly coupled to a web framework because most of the code lies in validating user input, handling errors, and directing users to the appropriate next page. As a result, many of the generic JS auth libraries include one or more web frameworks within them. For this reason, many users will find it preferrable to follow a SvelteKit-specific guide such as the examples found in [Lucia](https://lucia-next.pages.dev/) rather than having multiple web frameworks inside their project. diff --git a/packages/kit/src/exports/public.d.ts b/packages/kit/src/exports/public.d.ts index 4957dc67f439..77be062a3163 100644 --- a/packages/kit/src/exports/public.d.ts +++ b/packages/kit/src/exports/public.d.ts @@ -1061,7 +1061,7 @@ export interface RequestEvent< */ getClientAddress(): string; /** - * Contains custom data that was added to the request within the [`handle hook`](https://svelte.dev/docs/kit/hooks#Server-hooks-handle). + * Contains custom data that was added to the request within the [`server handle hook`](https://svelte.dev/docs/kit/hooks#Server-hooks-handle). */ locals: App.Locals; /** diff --git a/packages/kit/src/types/ambient.d.ts b/packages/kit/src/types/ambient.d.ts index bc936d57b31c..16ef13016deb 100644 --- a/packages/kit/src/types/ambient.d.ts +++ b/packages/kit/src/types/ambient.d.ts @@ -29,7 +29,7 @@ declare namespace App { } /** - * The interface that defines `event.locals`, which can be accessed in [hooks](https://svelte.dev/docs/kit/hooks) (`handle`, and `handleError`), server-only `load` functions, and `+server.js` files. + * The interface that defines `event.locals`, which can be accessed in server [hooks](https://svelte.dev/docs/kit/hooks) (`handle`, and `handleError`), server-only `load` functions, and `+server.js` files. */ export interface Locals {} diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts index feb9eca1714a..491de54d9698 100644 --- a/packages/kit/types/index.d.ts +++ b/packages/kit/types/index.d.ts @@ -1043,7 +1043,7 @@ declare module '@sveltejs/kit' { */ getClientAddress(): string; /** - * Contains custom data that was added to the request within the [`handle hook`](https://svelte.dev/docs/kit/hooks#Server-hooks-handle). + * Contains custom data that was added to the request within the [`server handle hook`](https://svelte.dev/docs/kit/hooks#Server-hooks-handle). */ locals: App.Locals; /** @@ -2270,7 +2270,7 @@ declare namespace App { } /** - * The interface that defines `event.locals`, which can be accessed in [hooks](https://svelte.dev/docs/kit/hooks) (`handle`, and `handleError`), server-only `load` functions, and `+server.js` files. + * The interface that defines `event.locals`, which can be accessed in server [hooks](https://svelte.dev/docs/kit/hooks) (`handle`, and `handleError`), server-only `load` functions, and `+server.js` files. */ export interface Locals {}