refactor: 📝 Move documentation to a custom VitePress site

docs/frontend/auth.md

@@ -0,0 +1,139 @@
+# Frontend Authentication
+
+Multiple API routes are exposed for authentication, to be used by frontend developers.
+
+> [!INFO]
+> 
+> These are different from the Client API routes, which are used by clients to interact with the Mastodon API.
+
+A frontend is a web application that is designed to be the primary user interface for an instance. It is used also used by clients to perform authentication.
+
+## Get Frontend Configuration
+
+```http
+GET /api/v1/frontend/config
+```
+
+Retrieves the frontend configuration for the instance. This returns whatever the `frontend.settings` object is set to in the Versia Server configuration.
+
+This behaves like the `/api/v1/preferences` endpoint in the Mastodon API, but is specific to the frontend. These values are arbitrary and can be used for anything.
+
+Frontend developers should always namespace their keys to avoid conflicts with other keys.
+
+- **Returns**: Object with arbitrary keys and values.
+- **Authentication**: Not required
+- **Permissions**: None
+- **Version History**:
+  - `0.7.0`: Added.
+
+### Request
+
+#### Example
+
+```http
+GET /api/v1/frontend/config
+```
+
+### Response
+
+#### `200 OK`
+
+Frontend configuration.
+
+```json
+{
+    "pub.versia.fe:theme": "dark",
+    "pub.versia.fe:custom_css": "body { background-color: black; }",
+    "net.googly.frontend:spoiler_image": "https://example.com/spoiler.png"
+}
+```
+
+## Sign In
+
+```http
+POST /api/auth/login
+```
+
+Allows users to sign in to the instance. This is the first step in the authentication process.
+
+- **Returns**: `302 Found` with a `Location` header to redirect the user to the next step, as well as a `Set-Cookie` header with the session JWT.
+- **Authentication**: Not required
+- **Permissions**: None
+- **Version History**:
+  - `0.7.0`: First documented.
+
+### Request
+
+- `identifier` (string, required): The username or email of the user. Case-insensitive.
+- `password` (string, required): The password of the user.
+
+#### Query Parameters
+
+- `client_id` (string, required): Client ID of the [application](https://docs.joinmastodon.org/entities/Application/) that is making the request.
+- `redirect_uri` (string, required): Redirect URI of the [application](https://docs.joinmastodon.org/entities/Application/) that is making the request. Must match the saved value.
+- `response_type` (string, required): Must be `code`.
+- `scope` (string, required): OAuth2 scopes. Must match the value indicated in the [application](https://docs.joinmastodon.org/entities/Application/).
+
+#### Example
+
+```http
+POST /api/auth/login?client_id=123&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&response_type=code&scope=read%20write
+Content-Type: application/json
+
+{
+    "identifier": "bobjones@gmail.com",
+    "password": "hunter2"
+}
+```
+
+### Response
+
+#### `302 Found`
+
+Redirects the user to the consent page with some query parameters. The frontend should redirect the user to this URL.
+
+This response also has a `Set-Cookie` header with a [JSON Web Token](https://jwt.io/) that contains the user's session information. This JWT is signed with the instance's secret key, and must be included in all subsequent authentication requests.
+
+```http
+HTTP/2.0 302 Found
+Location: /oauth/consent?client_id=123&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&response_type=code&scope=read%20write
+Set-Cookie: jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=3600
+```
+
+## SSO Sign In
+
+```http
+POST /oauth/sso
+```
+
+Allows users to sign in to the instance using an external OpenID Connect provider.
+
+- **Returns**: `302 Found` with a `Location` header to redirect the user to the next step.
+- **Authentication**: Not required
+- **Permissions**: None
+- **Version History**:
+  - `0.7.0`: First documented.
+
+### Request
+
+#### Query Parameters
+
+- `client_id` (string, required): Client ID of the [application](https://docs.joinmastodon.org/entities/Application/) that is making the request.
+- `issuer` (string, required): The ID of the OpenID Connect provider, as found in `/api/{v1,v2}/instance`.
+
+#### Example
+
+```http
+POST /oauth/sso?client_id=123&issuer=google
+```
+
+### Response
+
+#### `302 Found`
+
+Redirects the user to the OpenID Connect provider's login page.
+
+```http
+HTTP/2.0 302 Found
+Location: https://accounts.google.com/o/oauth2/auth?client_id=123&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&response_type=code&scope=openid%20email&state=123
+```

docs/frontend/routes.md

@@ -0,0 +1,53 @@
+# Frontend Routes
+
+Frontend implementors must implement these routes for correct operation of the instance.
+
+The location of these routes can be configured in the Versia Server configuration at `frontend.routes`:
+
+## Login Form
+
+```http
+GET /oauth/authorize
+```
+
+This route should display a login form for the user to enter their username and password, as well as a list of OpenID providers to use if available.
+
+The form should submit to [`POST /api/auth/login`](./auth.md#sign-in), or to the OpenID Connect flow.
+
+Configurable in the Versia Server configuration at `frontend.routes.login`.
+
+## Consent Form
+
+```http
+GET /oauth/consent
+```
+
+This route should display a consent form for the user to approve the requested application permissions, after logging in.
+
+The form should submit an OpenID Connect authorization request at `POST /oauth/authorize`, with the correct [application](https://docs.joinmastodon.org/entities/Application/) data (client ID, redirect URI, etc.). Do not forget the JWT cookie.
+
+### Submission Example
+
+```http
+POST /oauth/authorize
+Content-Type: application/json
+Cookie: jwt=...
+
+{
+    "client_id": "client_id",
+    "response_type": "code",
+    "redirect_uri": "https://example.com/callback",
+    "scope": "read write",
+    "state": "state123",
+    "code_challenge": "code_challenge",
+    "code_challenge_method": "S256",
+    "response_type": "code"
+}
+```
+
+### Submission Response
+
+```http
+HTTP/2.0 302 Found
+Location: https://example.com/callback?code=code&state=state123
+```