docs: auth guide (#12810)

Co-authored-by: Tee Ming <chewteeming01@gmail.com>

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

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.

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;
 	/**

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 {}
 

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 {}