diff --git a/README.md b/README.md index f9dea7fd..3a9d3402 100644 --- a/README.md +++ b/README.md @@ -32,10 +32,13 @@ Operational deep dives: ## Authentication (Clerk) -Clerk is **optional for local/self-host**. +**Clerk is currently required**. -- The frontend enables Clerk only when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` is set. -- If you’re not configuring Clerk locally, keep Clerk env vars **unset/blank**. +You must configure Clerk keys for: +- the frontend (`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`) +- the backend (`CLERK_SECRET_KEY`) + +See: [`docs/deployment/README.md`](./docs/deployment/README.md#clerk-auth-notes). ## Deployment modes @@ -50,6 +53,9 @@ cp .env.example .env # NEXT_PUBLIC_API_URL must be reachable from the *browser* (host), not an internal Docker network name. # Missing/blank NEXT_PUBLIC_API_URL will break frontend API calls (e.g. Activity feed). +# REQUIRED: Clerk config. +# Provide real Clerk values via frontend/.env (recommended) and backend/.env. + docker compose -f compose.yml --env-file .env up -d --build ``` diff --git a/docs/02-quickstart.md b/docs/02-quickstart.md index 0952efba..08c37187 100644 --- a/docs/02-quickstart.md +++ b/docs/02-quickstart.md @@ -11,4 +11,4 @@ After `docker compose up`: ## Common gotchas - `NEXT_PUBLIC_API_URL` must be reachable from your browser (host), not just from inside Docker. -- If you are not configuring Clerk locally, ensure Clerk env vars are **unset/blank** so Clerk stays gated off. +- Clerk auth is required; ensure Clerk keys are configured (see `docs/deployment/README.md`). diff --git a/docs/06-configuration.md b/docs/06-configuration.md index e4998c65..855f0241 100644 --- a/docs/06-configuration.md +++ b/docs/06-configuration.md @@ -88,8 +88,8 @@ This table is based on `backend/app/core/config.py`, `.env.example`, `backend/.e | Variable | Required? | Purpose | Default / example | Footguns | |---|---:|---|---|---| | `NEXT_PUBLIC_API_URL` | **yes** | Backend base URL used by the browser | `http://localhost:8000` | Must be browser-reachable | -| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | optional | Enables Clerk in the frontend when set | (none) | Placeholder values can unintentionally enable Clerk | -| `CLERK_SECRET_KEY` | depends | Used for Clerk flows (e.g. E2E) | (none) | Don’t commit; required for some testing setups | +| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | **yes** | Enables Clerk in the frontend | (none) | Must be a real publishable key | +| `CLERK_SECRET_KEY` | **yes** | Clerk secret key used by the frontend (server-side) and E2E | (none) | Do not commit; required for Clerk-enabled operation | | `NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL` | optional | Post-login redirect | `/boards` | — | | `NEXT_PUBLIC_CLERK_SIGN_UP_FORCE_REDIRECT_URL` | optional | Post-signup redirect | `/boards` | — | | `NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL` | optional | Fallback redirect | `/boards` | — | diff --git a/docs/07-api-reference.md b/docs/07-api-reference.md index 9ae4bf99..346ffc2b 100644 --- a/docs/07-api-reference.md +++ b/docs/07-api-reference.md @@ -12,7 +12,7 @@ It is derived from `backend/app/main.py` (router registration) and `backend/app/ - API prefix: `/api/v1/*` (see `backend/app/main.py`) ## Auth model (recap) -- **Clerk (user auth)**: used by the human web UI; frontend enables Clerk when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` is set; backend verifies JWTs when `CLERK_JWKS_URL` is configured (see `backend/app/core/auth.py`). +- **Clerk (user auth)**: used by the human web UI; frontend enables Clerk when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` is set; backend verifies requests using `CLERK_SECRET_KEY` via the Clerk SDK (see `backend/app/core/auth.py`). - **X-Agent-Token (agent auth)**: used by automation/agents; send header `X-Agent-Token: ` to `/api/v1/agent/*` endpoints (see `backend/app/core/agent_auth.py`). ## Route groups (modules) diff --git a/docs/10-troubleshooting.md b/docs/10-troubleshooting.md index c3f59459..8e6ef381 100644 --- a/docs/10-troubleshooting.md +++ b/docs/10-troubleshooting.md @@ -13,8 +13,8 @@ This is the “quick triage” page. For detailed playbooks and diagnostics, use - Check backend `/healthz`. ### Frontend keeps redirecting / Clerk errors -- If you’re running locally without Clerk, keep `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` unset/blank. -- See: [repo README Clerk note](../README.md#note-on-auth-clerk). +- Verify your Clerk keys are set correctly in the frontend environment. +- See: `docs/deployment/README.md` (Clerk auth notes). ### Backend returns 5xx - Check DB connectivity (`DATABASE_URL`) and migrations. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index f77dfb87..a579630b 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -29,9 +29,11 @@ flowchart LR - Routes/pages: `frontend/src/app/*` (Next.js App Router) - API utilities: `frontend/src/lib/*` and `frontend/src/api/*` -**Auth (Clerk, required for now)** -- The codebase includes gating so CI/local can run without secrets, but real deployments should configure Clerk. -- See `frontend/src/auth/clerkKey.ts`, `frontend/src/auth/clerk.tsx`, and `frontend/src/proxy.ts`. +**Auth (Clerk, required)** +- Clerk is required for real deployments and currently required by backend config (see `backend/app/core/config.py`). +- Frontend uses Clerk when keys are configured; see `frontend/src/auth/clerkKey.ts` and `frontend/src/auth/clerk.tsx`. +- Backend authenticates requests using the Clerk SDK and `CLERK_SECRET_KEY`; see `backend/app/core/auth.py`. + ### Backend (FastAPI) - Location: `backend/` @@ -62,11 +64,9 @@ Mission Control can call into an OpenClaw Gateway over WebSockets. 2. Frontend calls backend endpoints under `/api/v1/*`. 3. Backend reads/writes Postgres. -### Auth (Clerk — required for now) -- **Frontend** enables Clerk when a publishable key is present/valid. -- **Backend** uses `fastapi-clerk-auth` when `CLERK_JWKS_URL` is configured. - - See `backend/app/core/auth.py`. - +### Auth (Clerk — required) +- **Frontend** uses Clerk when keys are configured (see `frontend/src/auth/*`). +- **Backend** authenticates requests using the Clerk SDK and `CLERK_SECRET_KEY` (see `backend/app/core/auth.py`). ### Agent access (X-Agent-Token) Automation/agents can use the “agent” API surface: - Endpoints under `/api/v1/agent/*` (router: `backend/app/api/agent.py`). diff --git a/docs/deployment/README.md b/docs/deployment/README.md index 52243354..0d5aba68 100644 --- a/docs/deployment/README.md +++ b/docs/deployment/README.md @@ -15,7 +15,7 @@ When running Compose, you get: - Health check: `GET /healthz` - **Frontend UI** (Next.js) on `http://localhost:${FRONTEND_PORT:-3000}` -Auth (Clerk) is **required** right now. You must configure Clerk keys for the frontend, and configure `CLERK_JWKS_URL` for the backend so protected API routes can verify JWTs. +Auth (Clerk) is **required** right now. You must configure Clerk keys for the frontend and backend (`CLERK_SECRET_KEY`). ## Requirements @@ -133,18 +133,24 @@ NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/boards NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/boards ``` -### Backend (JWT verification) +### Backend (auth) -The backend verifies Clerk JWTs using **`CLERK_JWKS_URL`**. +The backend authenticates requests using the Clerk SDK and **`CLERK_SECRET_KEY`** (see `backend/app/core/auth.py`). -- Compose loads `backend/.env.example` by default, where `CLERK_JWKS_URL` is empty. -- For a real deployment, provide a real value either by: - 1) creating `backend/.env` and updating `compose.yml` to load it (preferred), **or** - 2) adding `CLERK_JWKS_URL: ${CLERK_JWKS_URL}` under `backend.environment` and setting it in root `.env`. +Create `backend/.env` (this file is **not** committed) with at least: -Related backend env vars (optional tuning): -- `CLERK_VERIFY_IAT` (default: true) -- `CLERK_LEEWAY` (default: 10.0) +```env +CLERK_SECRET_KEY=sk_test_your_real_key + +# Optional tuning +CLERK_API_URL=https://api.clerk.com +CLERK_VERIFY_IAT=true +CLERK_LEEWAY=10.0 +``` + +Then either: +1) update `compose.yml` to load `backend/.env` (recommended), or +2) pass the values via `services.backend.environment`. **Security:** treat `CLERK_SECRET_KEY` like a password. Do not commit it.