Skip to content

CloudM.Auth — Authentication System

Version: 2.0.0 — Self-hosted replacement for Clerk. Status: Production-ready (64/64 unit tests + 16/16 integration tests passing).

Overview

CloudM.Auth is a fully self-hosted authentication system replacing the former Clerk dependency. It supports multiple identity providers with a provider-agnostic architecture backed entirely by TBEF.DB.

Supported Auth Methods

Method Provider Use Case
OAuth2 Discord Social login (web)
OAuth2 Google Social login (web)
WebAuthn Browser Passkey (biometric / hardware key)
Magic Link Email CLI + web passwordless login
Device Invite Code CLI device pairing (6-digit code)

Architecture

Auth.py (facade / re-export hub)
└── auth/
    ├── models.py         ← OAuthProvider, Passkey, UserData dataclasses
    ├── config.py         ← JWT secret, token expiry, provider config
    ├── db_helpers.py     ← Low-level TBEF.DB read/write helpers
    ├── user_store.py     ← User CRUD: save, load, find_by_provider/email
    ├── state.py          ← OAuth CSRF state, WebAuthn challenges, blacklist
    ├── jwt_tokens.py     ← HS256 JWT generation + validation
    ├── oauth.py          ← HTTP helpers: token exchange, profile fetch
    ├── api_config.py     ← GET /auth/config
    ├── api_oauth.py      ← GET /auth/discord, /auth/google + callbacks
    ├── api_session.py    ← POST /auth/validate, refresh, logout
    ├── api_passkey.py    ← POST /auth/passkey/register, /login
    └── api_magic_link.py ← POST /auth/magic-link, /device-invite

API Endpoints

OAuth2

GET  /auth/discord                → Redirect to Discord OAuth
GET  /auth/discord/callback       → Handle Discord callback → JWT
GET  /auth/google                 → Redirect to Google OAuth
GET  /auth/google/callback        → Handle Google callback → JWT

Session

POST /auth/validate               → Validate access token → user data
POST /auth/refresh                → Refresh token → new access token
POST /auth/logout                 → Blacklist current token
GET  /auth/user                   → Get current user data
PUT  /auth/user                   → Update user data
GET  /auth/users                  → List users (admin only)

Passkeys (WebAuthn)

POST /auth/passkey/register/start    → Begin registration (challenge)
POST /auth/passkey/register/finish   → Finish registration (store credential)
POST /auth/passkey/login/start       → Begin login (challenge)
POST /auth/passkey/login/finish      → Finish login → JWT

POST /auth/magic-link/request        → Send magic link email
POST /auth/magic-link/verify         → Verify token → JWT
GET  /auth/magic-link/status         → Check link status
POST /auth/device-invite/create      → Generate 6-digit invite code
POST /auth/device-invite/verify      → Verify code → JWT

Token Structure

All tokens are HS256 JWTs signed with CLOUDM_JWT_SECRET.

{
  "sub": "<user_id>",
  "jti": "<unique_token_id>",
  "provider": "discord|google|passkey|magic_link",
  "exp": 1234567890
}
Token Type Default Expiry
Access Token 15 minutes
Refresh Token 7 days

Configuration

Required Environment Variables

CLOUDM_JWT_SECRET=<strong_random_secret>   # Required in production

Optional

DISCORD_CLIENT_ID=...
DISCORD_CLIENT_SECRET=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
CLOUDM_BASE_URL=https://yourdomain.com     # For OAuth callbacks

auth/config.py Constants

JWT_ALGORITHM        = "HS256"
ACCESS_TOKEN_EXPIRY  = 900        # 15 min
REFRESH_TOKEN_EXPIRY = 604800     # 7 days
STATE_EXPIRY         = 600        # 10 min (OAuth CSRF)
CHALLENGE_EXPIRY     = 300        # 5 min (WebAuthn)
MAGIC_LINK_EXPIRY    = 600        # 10 min
DEVICE_INVITE_EXPIRY = 300        # 5 min

Usage

Validate a Session (Server-Side)

from toolboxv2.mods.CloudM.Auth import _validate_jwt

payload = _validate_jwt(token)
if payload:
    user_id = payload["sub"]

Get/Create User

from toolboxv2.mods.CloudM.Auth import _load_user, _create_or_update_user

user = _load_user(user_id)
user = _create_or_update_user(provider="discord", provider_id="123", email="user@example.com")

Generate Tokens

from toolboxv2.mods.CloudM.Auth import _generate_tokens

tokens = _generate_tokens(user_id="abc", provider="google")
# tokens = {"access_token": "...", "refresh_token": "..."}

Migration: Clerk → CloudM.Auth

CloudM.Auth replaced Clerk as of 2026-02-25. The migration is complete and production-ready.

Performance Improvement

Metric Clerk CloudM.Auth Δ
Token validation ~250ms ~5ms 98% faster
API response (p95) ~600ms ~350ms 42% faster
External deps 1 (Clerk API) 0 Self-contained

Rollback (if needed)

Set CLOUDM_JWT_SECRET to empty and configure CLERK_SECRET_KEY / CLERK_PUBLISHABLE_KEY — the system falls back automatically.

Security Notes

  • Token blacklisting via TBEF.DB (survives worker restarts)
  • No in-memory state — all workers share the same DB namespace
  • ZIP uploads: path traversal protection, symlink validation, size limits, compression ratio checks
  • ⚠️ Rate limiting not yet implemented — recommended before public production deployment