GearBox/docs/authentication.md

Authentication

GearBox uses a public-read, authenticated-write model. All GET endpoints are publicly accessible. Any request that modifies data (POST, PUT, PATCH, DELETE) requires authentication.

Table of Contents

• Overview
• OIDC Authentication (Logto)
• Logto Setup Checklist
• API Keys
• Account Management
• Auth Middleware Behavior
• Frontend Behavior

---

Overview

Authentication is handled by Logto, a self-hosted open-source OIDC provider. Users register and log in through Logto's sign-in experience. GearBox validates OIDC sessions and provides in-app account management via the Logto Management API.

Auth methods:

• Browser sessions — OIDC via Logto (redirect flow)
• API keys — X-API-Key header for programmatic access (MCP, scripts)
• OAuth 2.1 + PKCE — for Claude mobile/web MCP connections

---

OIDC Authentication (Logto)

Required Environment Variables

OIDC_ISSUER=https://your-logto-domain/oidc    # Logto OIDC issuer URL
OIDC_CLIENT_ID=<client-id>                     # From Logto app settings
OIDC_CLIENT_SECRET=<client-secret>             # From Logto app settings
OIDC_AUTH_SECRET=<random-32-char-hex>          # Session encryption key
OIDC_SCOPES="openid profile email"             # Must match Logto app scopes
OIDC_REDIRECT_URI=https://your-app/callback    # Must match Logto redirect URI

Management API (M2M)

GearBox uses the Logto Management API for in-app account management (password change, email change, account deletion). This requires a Machine-to-Machine (M2M) application in Logto.

LOGTO_MANAGEMENT_API_ENDPOINT=https://your-logto-domain  # Logto base URL
LOGTO_M2M_APP_ID=<m2m-app-id>                            # From Logto M2M app
LOGTO_M2M_APP_SECRET=<m2m-app-secret>                    # From Logto M2M app

---

Logto Setup Checklist

Complete these steps in the Logto admin console after deployment.

Application Setup

• Create a Traditional Web application in Logto Console
• Set redirect URI to https://your-app/callback
• Note the Client ID and Client Secret for env vars
• Grant user scopes: openid, profile, email

Machine-to-Machine (M2M) Application

• Create an M2M application in Logto Console
• Grant access to the Logto Management API resource
• Note the M2M App ID and Secret for env vars

Branding & Sign-in Experience

• Upload GearBox logo in Logto Console > Sign-in Experience > Branding
• Set primary brand color to match GearBox (gray-700 / #374151)
• Set background color to white
• Customize sign-in page text if desired
• (Optional) Configure custom domain auth.gearbox.de in Logto Console > Settings

Social Connectors

• Add Google connector in Logto Console > Connectors > Social
  • Create OAuth 2.0 credentials in Google Cloud Console
  • Set authorized redirect URI to Logto's callback URL
• Add GitHub connector in Logto Console > Connectors > Social
  • Create OAuth App in GitHub Developer Settings
  • Set authorization callback URL to Logto's callback URL
• Enable both connectors in the Sign-in Experience

Email Verification & Password Policy

• Enable mandatory email verification at signup in Logto Console > Sign-up settings
• Set password policy: minimum 8 characters, require mixed case, require at least one number
  • Logto Console > Sign-in Experience > Password policy

Verification

After completing the checklist:

• Visit /login — GearBox logo and colors appear on Logto sign-in page
• Google and GitHub sign-in buttons are visible
• Create a new account — email verification is required before access
• Try a weak password (e.g., "abc") — rejected by policy
• Log in — redirected back to GearBox with session active

---

API Keys

API keys provide programmatic access for scripts, MCP clients, and integrations. Managed in Settings > API Keys.

Key behavior

• Keys are shown once at creation time. Store them securely.
• Keys are stored as a hash. Only the 8-character prefix is kept for display.
• Pass the key via the X-API-Key header.

POST /api/items
X-API-Key: gbk_a1b2c3d4...
Content-Type: application/json

{ "name": "Revelate Tangle", "categoryId": 2 }

API Endpoints

Method	Endpoint	Description
GET	/api/auth/keys	List all API keys (name, prefix, date)
POST	/api/auth/keys	Create a new key (returns full key once)
DELETE	/api/auth/keys/:id	Revoke a key

---

Account Management

All account management happens within GearBox — users never interact with Logto directly.

Profile (/profile)

The profile page has four sections:

1. Profile Info — display name, bio, avatar (editable)
2. Account Info — email (editable via Logto Management API), member-since date
3. Security — change password
4. Danger Zone — delete account

API Endpoints

Method	Endpoint	Description
GET	/api/auth/me	Current session state (user, email, createdAt)
PUT	/api/auth/profile	Update display name, bio, avatar
POST	/api/account/password	Change password (requires current password)
POST	/api/account/email	Change email (updates Logto)
DELETE	/api/account	Delete account (anonymizes public content)

Account Deletion

When a user deletes their account:

• Personal items, threads, and private data are deleted
• Public setups and catalog contributions are preserved, attributed to "Deleted User"
• User is removed from Logto

---

Auth Middleware Behavior

The middleware on /api/* (excluding /api/auth/* and /api/account/*) follows:

1. GET requests — always allowed, no auth check
2. X-API-Key header present — verified against stored hashes
3. Authorization: Bearer header present — verified as OAuth token
4. OIDC session cookie present — validated via @hono/oidc-auth
5. No credentials — returns 401 { "error": "Authentication required" }

---

Frontend Behavior

• Anonymous visitors see all public content (catalog, public setups, profiles, discovery feed)
• A "Sign in" button appears in the top nav for anonymous users
• Write actions (add to collection, create thread, etc.) show an auth prompt modal
• The floating action button (FAB) is hidden when not authenticated
• Authenticated users see their avatar in the top nav with a dropdown menu linking to Profile and Settings