docs(api-server): add authentication feature documentation

- Describe passwordless email and code sign-in process
- Explain anonymous guest sign-in and conversion to permanent account
- Detail session management using JSON Web Tokens (JWT)
- Outline secure sign-out procedure

Author: fulleni

src/content/docs/api-server/features/authentication.mdx

@@ -0,0 +1,38 @@
+---
+title: Feature: Authentication
+description: A deep dive into the API server's authentication flows, including passwordless sign-in, guest accounts, and token management.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The API server provides a robust and flexible authentication system designed to handle various user scenarios securely. It uses a passwordless email and code flow, supports anonymous guest access, and manages sessions using JSON Web Tokens (JWT).
+
+### Key Authentication Flows
+
+#### 1. Passwordless Email + Code Sign-In
+
+Instead of traditional passwords, the system uses a secure one-time code sent to the user's email address.
+
+-   **Requesting a Code (`/api/v1/auth/request-code`):** The client sends the user's email to this endpoint. The server generates a 6-digit code, stores it temporarily, and emails it to the user.
+-   **Verifying a Code (`/api/v1/auth/verify-code`):** The client sends the user's email and the 6-digit code. The server validates the code. If correct, it either signs the user in (if they exist) or creates a new account and returns a JWT.
+
+<Aside title="Dashboard Login">
+The `request-code` endpoint has a special mode for dashboard logins. If the request includes `"isDashboardLogin": true`, the server first verifies that the user exists and has the necessary `admin` or `publisher` role before sending a code. This prevents unauthorized users from attempting to access the dashboard.
+</Aside>
+
+#### 2. Anonymous Guest Sign-In
+
+-   **Creating a Guest Account (`/api/v1/auth/anonymous`):** When a new user opens the app for the first time, the client can call this endpoint to create a temporary guest account. The server returns a new `User` object with a `guestUser` role and a JWT.
+-   **Guest-to-Permanent Conversion:** If a guest user decides to sign up with their email, the `verify-code` flow intelligently handles the conversion. The guest account's data (like saved preferences) is preserved as the account is upgraded to a `standardUser` role with the verified email.
+
+#### 3. Session Management with JWT
+
+All authenticated sessions are managed using JSON Web Tokens (JWT).
+
+-   **Token Generation:** Upon successful authentication, the server generates a JWT containing the user's ID, roles, and an expiration time.
+-   **Authenticated Requests:** The client must include this token in the `Authorization: Bearer <token>` header for all subsequent requests to protected endpoints.
+-   **Middleware:** A dedicated authentication middleware on the server is responsible for validating the token on every incoming request.
+
+#### 4. Secure Sign-Out
+
+-   **Token Invalidation (`/api/v1/auth/sign-out`):** When a user signs out, the client calls this endpoint. The server adds the token's unique identifier (JTI) to a blacklist, immediately invalidating it even before it naturally expires. This prevents the token from being reused.