learn-auth-share

# Auth & Share Security Authentication/authorization and share-security behavior across Auth0 scopes, Turnstile captcha verification, and map share/edit-access tokens. ## When To Use - You are changing protected endpoints, scopes, or role behavior. - You are changing admin login/session behavior in frontend. - You are changing share-link or password-protected edit access behavior. ## Canonical Files - `backend/app/core/security.py` - `backend/app/core/dependencies.py` - `backend/app/save_share/main.py` - `backend/app/core/config.py` - `app/src/app/lib/auth0.ts` - `app/src/app/admin/layout.tsx` - `app/src/app/hooks/useAuthRoutes.tsx` - `app/src/app/store/saveShareStore.ts` ## Hard Invariants - Protected backend routes must enforce required scopes via `auth.verify`. - Auth0 token validation must preserve audience/issuer/algorithm constraints. - Captcha-gated flows must verify token server-side. - Share-token payload and password behavior must remain compatible with frontend share/edit flows. - Public document access must not expose private document identifiers. ## Preferred Patterns - Add scope requirements explicitly on routes rather than implicit role checks. - Keep share/edit access flows using existing backend `save_share` endpoints. - Use existing Auth0 client session wiring in admin pages. - Keep secrets and key material in environment configuration only. ## Anti-Patterns - Broadening scopes or bypassing route security checks for convenience. - Performing captcha checks only in frontend. - Logging sensitive token/password data. - Returning internal IDs/secrets in public route responses. ## Change Checklist 1. Verify scope enforcement on all touched protected routes. 2. Verify token verification config (audience/issuer/algorithms) is unchanged or intentionally updated. 3. Verify captcha validation still runs for relevant form endpoints. 4. Verify share/password flow works for read/edit transitions. 5. Verify no sensitive data is exposed in logs/responses. ## Validation Commands - `cd backend && pytest -v tests/test_save_share.py tests/test_comments.py` - `cd app && bun run build` ## Common Failure Modes - 401/403 regressions from missing scopes in frontend-acquired tokens. - Broken admin pages from session/token wiring drift. - Password-protected map edit failures due to token/payload mismatch. - False captcha failures from env/config mistakes.