docs: add docs for altcha

docs/_sidebar.md

@@ -4,15 +4,16 @@
 
 * Get Started
 
-    * [Start with Docker](getstarted/docker.md)
-    * [Dev Server Setup](getstarted/dev.md)
+  * [Start with Docker](getstarted/docker.md)
+  * [Dev Server Setup](getstarted/dev.md)
 
 * Reference
 
-    * [Environment Variables](reference/env.md)
-    * [Database Migration Guide](reference/db-migration.md)
-    * [Editing Documentation](reference/editing-docs.md)
+  * [Environment Variables](reference/env.md)
+  * [Database Migration Guide](reference/db-migration.md)
+  * [Altcha Implementation](reference/altcha.md)
+  * [Editing Documentation](reference/editing-docs.md)
 
 * Updates
 
-    * [v1.2.0](updates/1.2.0.md)
+  * [v1.2.0](updates/1.2.0.md)

docs/getstarted/dev.md

@@ -29,11 +29,20 @@
    bunx auth secret
    ```
 
-5. **Configure environment variables**
+5. **Generate Altcha token**
+
+   If you plan to use the signup forms, you will need to use Altcha, a private proof-of-work CAPTCHA. All you need to do is execute the script below, and it will be written to your `.env` or `.env.local`.
+
+   ```bash
+   $ bun tools/hmac.ts
+   Successfully wrote ALTCHA_SECRETKEY to .env.local
+   ```
+
+6. **Configure environment variables**
 
    Following the environment variables section of this README, update your newly created `.env.local` file with your configuration.
 
-6. **Initialize Prisma**
+7. **Initialize Prisma**
 
    Because `web` uses a database for storing Git link statuses (and other things to come), you will need to initialize the SQLite database.
 
@@ -45,7 +54,7 @@
    bunx prisma migrate dev --name init
    ```
 
-7. **Start dev server**
+8. **Start dev server**
 
    ```bash
    bun dev

docs/getstarted/docker.md

@@ -36,11 +36,20 @@ A Docker setup requires both Docker *and* Docker Compose.
    bunx auth secret
    ```
 
-4. **Configure environment variables**
+4. **Generate Altcha token**
+
+   If you plan to use the signup forms, you will need to use Altcha, a private proof-of-work CAPTCHA. All you need to do is execute the script below, and it will be written to your `.env` or `.env.local`.
+
+   ```bash
+   $ bun tools/hmac.ts
+   Successfully wrote ALTCHA_SECRETKEY to .env.local
+   ```
+
+5. **Configure environment variables**
 
    Following the environment variables section of this README, update your newly created `.env.local` file with your configuration.
 
-5. **Initialize Prisma**
+6. **Initialize Prisma**
 
    Because `web` uses a database for storing Git link statuses (and other things to come),
    you will need to initialize the SQLite database.
@@ -52,11 +61,11 @@ A Docker setup requires both Docker *and* Docker Compose.
    bunx prisma migrate dev --name init
    ```
 
-6. **Setup environment variables**
+7. **Setup environment variables**
 
    Now is the time to go to the "Environment Variables" section and configure them in your `.env.local` file.
 
-7. **Bring the container up**
+8. **Bring the container up**
 
    ```bash
    docker compose up -d --build
@@ -66,7 +75,7 @@ A Docker setup requires both Docker *and* Docker Compose.
 
    You may customize the container with the included `docker-compose.yml` file if needed. Your server will start on port `3019` by default. We suggest using a reverse proxy to serve the site on a domain.
 
-8. **Complete Setup**
+9. **Complete Setup**
 
    If you would like to host the entire LibreCloud frontend and backend,
    you will also need to set up the following repositories and edit this project to work with *your* setup.

docs/reference/altcha.md

@@ -0,0 +1,47 @@
+# Altcha Implementation
+
+Altcha is a privacy-friendly CAPTCHA alternative that's used in the LibreCloud signup form to verify that users are not bots. This doc explains the implementation, setup, and configuration of Altcha with LibreCloud.
+
+## Basic Overview
+
+Altcha works by serving a proof-of-work-based CAPTCHA which doesn't require any fingerprinting/data collection. Our implementation does not use their API, and instead uses an endpoint, `/api/captcha/create`. The setup of this is nearly automatically.
+
+## Components
+
+1. **Widget** (`components/custom/Altcha.tsx`)
+
+   This component renders the Altcha widget for use in pages.
+
+2. **API Endpoint** (`app/api/captcha/create/route.ts`)
+
+   This endpoint generates the challenges with the altcha library.
+
+3. **Token Validation** (`lib/utils.ts`)
+
+   The utils file provides verification for submitted tokens from the client. This is what gets implemented into an API route which needs to be protected by Altcha. You can see an example of this in `app/api/users/create/route.ts`, which connects to `app/account/signup/page.tsx`.
+
+## Setup
+
+### Environment Variables
+
+To use Altcha, you need to set the following environment variable:
+
+```text
+ALTCHA_SECRETKEY=
+```
+
+#### Automatic Setup
+
+You should generate this with the provided `tools/hmac.ts` script. This is an important part of setup for people who want to take advantage of the signup forms.
+
+The script requires the existance of an `.env` or `.env.local` file. You should have had this created when you setup Auth.js with `bunx auth secret`.
+
+Execute the script like so:
+
+```bash
+bun tools/hmac.ts
+```
+
+## Debug Mode
+
+The Altcha widget is in debug mode when `NODE_ENV` is set to `"development"`. This is nice for testing but you should disable it in production.

docs/reference/env.md

@@ -17,6 +17,23 @@ With these variables, you can disable entire parts of the dashboard, such as reg
 | NEXT_PUBLIC_TELEGRAM_CHANNEL_URL | Changes the default Telegram channel link in Support dash | String - `https://t.me/...`            |
 | NEXT_PUBLIC_TELEGRAM_GROUP_URL   | Changes the default Telegram group link in Support dash   | String - `https://t.me/...`            |
 
+## Altcha
+
+Altcha is a privacy-friendly CAPTCHA alternative we use for bot traffic mitigation and anti-spam.
+It requires a secret key for generating and verifying challenges. The rest is handled by the API.
+
+| Environment Variable | Description                                               | Example                                |
+|----------------------|-----------------------------------------------------------|----------------------------------------|
+| ALTCHA_SECRETKEY     | Secret key for generating and verifying Altcha challenges | N/A                                    |
+
+### Automatic Secret Key Setup
+
+We've included an automatic setup script for your Altcha secret key. It generates and writes a secure token to your `.env` or `.env.local` file. You can execute this script like so:
+
+```bash
+bun tools/hmac.ts
+```
+
 ## Authentik
 
 We use [Auth.js](https://authjs.dev) to provide authentication for users through Authentik.