Add Credentials Auth

Author: mythz

content/docs/authentication/credentials.mdx

@@ -0,0 +1,234 @@
+---
+title: Credentials
+description: Learn how to use the built-in Credentials Auth extension for Username/Password auth, user management, and account security features in your llms .py application
+---
+
+The built-in [credentials](https://github.com/ServiceStack/llms/tree/main/llms/extensions/credentials) extension enables Username/Password authentication for your Application, including a Sign In page, user registration, role assignment, and account locking.
+
+It provides full user management through both the CLI and a web-based Admin UI, along with account self-service for all authenticated users.
+
+## Enable Credentials Auth
+
+Credentials is the **default** Auth Provider (`LLMS_AUTH=credentials`) which is automatically enabled when **at least one user** has been created. If no users exist, the extension disables itself and the app runs as the **default** user without authentication.
+
+## Getting Started
+
+Create your **admin** user from the CLI to enable authentication, the **"admin"** username automatically gets the `Admin` role:
+
+```bash
+llms --adduser admin
+# Enter password when prompted
+
+# Start server
+llms --serve 8000
+```
+
+When you start the server, authentication will now be enabled since at least one user exists and you'll be presented with the Sign In page. 
+
+<Screenshot src="/img/auth/signin.webp" alt="Sign In Page" />
+
+After logging in as `admin`, you can create additional users from the **Manage Users** page which can be accessed from the user menu. 
+
+## UI Features
+
+### User Menu
+
+After signing in, the user avatar dropdown shows:
+
+- **Username** and **My Account** link
+- **Manage Users** link (Admin only)
+- **Sign Out** button
+
+<Screenshot src="/img/auth/manage-users.webp" alt="Manage Users Page" />
+
+<Tip>Only users with the `Admin` role can access the **Manage Users** page</Tip>
+
+### Manage Users (Admin only)
+
+Accessible at `/admin` for users with the Admin role. Provides a table of all
+users showing:
+
+| Column     | Description                              |
+|------------|------------------------------------------|
+| Username   | Account name                             |
+| Roles      | Assigned roles (Admin badge highlighted) |
+| Status     | Active or Locked (with lock icon)        |
+| Created    | Account creation date                    |
+| Last Login | IP address and relative timestamp        |
+| Actions    | Per-user action buttons                  |
+
+Click **Create User** to create a new user account with password and optional `Admin` role.
+
+**Available actions per user:**
+
+- **Change Password** - Set a new password for any user (modal dialog)
+- **Lock** - Suspend the account with confirmation (not available for admins or yourself)
+- **Unlock** - Restore a locked account
+- **Delete** - Permanently remove the account with confirmation (cannot delete yourself)
+
+<ScreenshotsGallery className="mb-8" gridClass="grid grid-cols-1 md:grid-cols-2 gap-4" images={{
+    'Create User': '/img/auth/create-user.webp',
+    'Change Password': '/img/auth/change-password.webp',
+    'Lock User': '/img/auth/lock-user.webp',
+    'Delete User': '/img/auth/delete-user.webp',
+}} />
+
+### My Account
+
+Accessible at `/account` for all authenticated users. Shows your profile
+information (avatar, username, roles) and provides a **Change Password** button
+that requires your current password for verification.
+
+<Screenshot src="/img/auth/my-account.webp" alt="My Account Page" />
+
+Users can also change their avatar by clicking on their profile picture and uploading a new image:
+
+<Screenshot src="/img/auth/settings-avatar.webp" alt="Settings Page" />
+
+After uploading, the new avatar is displayed across the app, including the user menu and My Account page:
+
+<Screenshot src="/img/auth/my-account-avatar.webp" alt="Custom Avatar" />
+
+## CLI Commands
+
+All commands operate on the user store at `~/.llms/credentials/users.json`.
+
+### `--adduser USERNAME`
+
+Create a new user or update an existing user's password. Prompts for password
+with confirmation.
+
+```bash
+# Create a regular user
+llms --adduser alice
+
+# Create an admin (the username "admin" auto-assigns the Admin role)
+llms --adduser admin
+```
+
+### `--removeuser USERNAME`
+
+Delete a user and invalidate all their active sessions.
+
+```bash
+llms --removeuser alice
+```
+
+### `--listusers`
+
+List all users with their creation date and lock status.
+
+```bash
+llms --listusers
+#   admin  (created: 2025-03-15 10:30:00)
+#   alice  (created: 2025-03-15 11:00:00)
+#   bob    (created: 2025-03-16 09:15:00)  LOCKED: Account suspended
+```
+
+### `--lockuser [USERNAME]`
+
+Lock a user account, preventing them from signing in. All active sessions are
+immediately invalidated. Prompts for a lock reason (defaults to "Account suspended").
+
+```bash
+# Lock a specific user
+llms --lockuser bob
+
+# List users with lock status (omit username)
+llms --lockuser
+```
+
+### `--unlockuser USERNAME`
+
+Restore access for a locked user account.
+
+```bash
+llms --unlockuser bob
+```
+
+## How To
+
+### Set up authentication for the first time
+
+```bash
+# 1. Create an admin user
+llms --adduser admin
+# Enter and confirm password
+
+# 2. Start the server
+llms
+
+# 3. Sign in at the web UI, then use Manage Users to create more accounts
+```
+
+### Create multiple users from the CLI
+
+```bash
+llms --adduser admin
+llms --adduser alice
+llms --adduser bob
+```
+
+### Reset a user's password from the CLI
+
+Re-running `--adduser` with an existing username updates their password:
+
+```bash
+llms --adduser alice
+# "User 'alice' already exists. Updating password."
+# Enter new password
+```
+
+### Reset a user's password from the UI
+
+Sign in as an Admin, go to **Manage Users** (`/admin`), and click the key icon
+next to the user to open the Change Password dialog.
+
+### Temporarily disable a user
+
+```bash
+# Lock the account
+llms --lockuser bob
+# Reason: "On vacation until March"
+
+# Later, restore access
+llms --unlockuser bob
+```
+
+Or from the UI: go to **Manage Users**, click the lock icon next to the user,
+and confirm.
+
+### Change your own password
+
+Sign in, click your avatar, select **My Account**, and click **Change Password**.
+You'll need to enter your current password first.
+
+### Switch to a different auth provider
+
+```bash
+# Use GitHub OAuth instead
+llms --auth github_auth
+
+# Or disable auth entirely
+llms --auth none
+```
+
+## Password Storage
+
+Passwords are never stored in plain text. Each password is hashed using **SHA-256**
+with a unique random salt:
+
+1. A 16-byte random salt is generated via `secrets.token_hex(16)`
+2. The salt is prepended to the password and the combination is SHA-256 hashed
+3. The result is stored as `salt:hex_digest` in the `password_hash` field of `users.json`
+
+Verification re-hashes the provided password with the stored salt and compares the
+result against the stored digest.
+
+## Session Details
+
+- Sessions are stored in memory and persisted to `~/.llms/credentials/sessions/`
+- Sessions expire after **30 days**
+- Sessions survive server restarts (loaded from disk on startup)
+- The session token is stored in an HTTP-only cookie (`llms-token`)
+- Locking or deleting a user immediately invalidates all their sessions

content/docs/deployment/github-oauth.mdx …tent/docs/authentication/github-auth.mdxcontent/docs/deployment/github-oauth.mdx renamed to content/docs/authentication/github-auth.mdx content/docs/deployment/github-oauth.mdx renamed to content/docs/authentication/github-auth.mdx

@@ -1,5 +1,5 @@
 ---
-title: GitHub OAuth Setup
+title: GitHub Auth
 description: Secure your llms.py deployment with GitHub OAuth authentication
 ---
 
@@ -17,13 +17,26 @@ The [github_auth](https://github.com/ServiceStack/llms/tree/main/llms/extensions
 - ✅ Optional user access restrictions
 - ✅ Environment variable support
 
+## Enable GitHub Auth Provider
+
+GitHub Auth can either be enabled via environment `LLMS_AUTH` variable:
+
+```bash
+export LLMS_AUTH=github_auth
+```
+
+Or with the `--auth github_auth` flag when starting the server:
+
+```bash
+llms --auth github_auth
+```
+
 ## Configuration
 
 Create a config file at `~/.llms/users/default/github_auth/config.json`:
 
 ```json
 {
-  "enabled": true,
   "client_id": "GITHUB_CLIENT_ID",
   "client_secret": "GITHUB_CLIENT_SECRET",
   "redirect_uri": "http://localhost:8000/auth/github/callback",

content/docs/authentication/meta.json

@@ -0,0 +1,8 @@
+{
+  "title": "Authentication",
+  "defaultOpen": true,
+  "pages": [
+    "credentials",
+    "github-auth"
+  ]
+}

content/docs/deployment/meta.json

@@ -4,7 +4,6 @@
   "pages": [
     "index",
     "docker",
-    "custom-build",
-    "github-oauth"
+    "custom-build"
   ]
 }

content/docs/mcp/meta.json

@@ -1,6 +1,6 @@
 {
   "title": "Model Context Protocol",
-  "defaultOpen": true,
+  "defaultOpen": false,
   "pages": [
     "fast_mcp",
     "gemini_gen_mcp",

content/docs/media-generation/meta.json

@@ -1,6 +1,6 @@
 {
   "title": "Media Generation",
-  "defaultOpen": true,
+  "defaultOpen": false,
   "pages": [
     "image-generation",
     "audio-generation",

content/docs/meta.json

@@ -6,11 +6,12 @@
     "v3",
     "getting-started",
     "features",
-    "multimodal",
-    "media-generation",
     "extensions",
     "mcp",
+    "multimodal",
+    "media-generation",
     "cli",
+    "authentication",
     "configuration",
     "deployment"
   ]

content/docs/multimodal/meta.json

@@ -1,6 +1,6 @@
 {
   "title": "Multimodal",
-  "defaultOpen": true,
+  "defaultOpen": false,
   "pages": [
     "index",
     "image",