142 lines
3.6 KiB
Markdown
142 lines
3.6 KiB
Markdown
# cfw-auth account center operations
|
|
|
|
## Local development
|
|
|
|
Install dependencies once:
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
Apply local D1 migrations:
|
|
|
|
```bash
|
|
pnpm db:apply:local
|
|
```
|
|
|
|
Start the Worker:
|
|
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
|
|
Wrangler may choose `http://localhost:8787` by default. If that port is already in use, start it on the auth base URL configured in `wrangler.jsonc`:
|
|
|
|
```bash
|
|
pnpm exec wrangler dev --port 8788
|
|
```
|
|
|
|
## Verification
|
|
|
|
Run the full local readiness check before deploying:
|
|
|
|
```bash
|
|
pnpm ready
|
|
```
|
|
|
|
This verifies the generated Better Auth migration, TypeScript, and Vitest suites.
|
|
|
|
After changing Better Auth plugins or persistence-related options, regenerate and review the migration:
|
|
|
|
```bash
|
|
pnpm db:generate
|
|
pnpm ready
|
|
```
|
|
|
|
## Runtime smoke checks
|
|
|
|
With the local Worker running on `http://localhost:8788`, verify the generated API reference and OpenAPI schema:
|
|
|
|
```bash
|
|
curl -i http://localhost:8788/api/auth/reference
|
|
curl -i http://localhost:8788/api/auth/open-api/generate-schema
|
|
```
|
|
|
|
Password reset requests use Better Auth's current `/request-password-reset` endpoint:
|
|
|
|
```bash
|
|
curl -i -X POST http://localhost:8788/api/auth/request-password-reset \
|
|
-H 'Content-Type: application/json' \
|
|
-H 'Origin: http://localhost:8787' \
|
|
--data '{"email":"missing@example.com","redirectTo":"http://localhost:8787/reset-password"}'
|
|
```
|
|
|
|
The deprecated or older `/forget-password` route is not exposed by the current Better Auth configuration.
|
|
|
|
## Configuration
|
|
|
|
Non-secret defaults live in `wrangler.jsonc`:
|
|
|
|
- `BETTER_AUTH_URL`
|
|
- `TRUSTED_ORIGINS`
|
|
- `MAIL_PROVIDER`
|
|
- `MAIL_FROM`
|
|
- `CAPTCHA_PROVIDER`
|
|
|
|
Performance-related non-secret defaults also live in `wrangler.jsonc`:
|
|
|
|
- `BETTER_AUTH_SESSION_COOKIE_CACHE_MAX_AGE`: Better Auth session cookie cache TTL in seconds. Default is `300`. Lower it if session revocation or role changes must propagate faster.
|
|
- `API_KEY_DEFER_UPDATES`: When `true`, API key request counters and timestamps are deferred through Better Auth background tasks and Worker `waitUntil`.
|
|
|
|
Auth request latency is logged as structured JSON with:
|
|
|
|
- `event=auth_request`
|
|
- `method`
|
|
- `path`
|
|
- `status`
|
|
- `durationMs`
|
|
- optional `colo`
|
|
- optional `cfRay`
|
|
|
|
Do not log request bodies, cookies, authorization headers, API keys, emails, phone numbers, or OTP codes.
|
|
|
|
Set secrets with Wrangler:
|
|
|
|
```bash
|
|
wrangler secret put BETTER_AUTH_SECRET
|
|
wrangler secret put RESEND_API_KEY
|
|
wrangler secret put CAPTCHA_SECRET_KEY
|
|
```
|
|
|
|
Optional provider secrets are only needed when enabling the corresponding feature:
|
|
|
|
```bash
|
|
wrangler secret put GOOGLE_CLIENT_ID
|
|
wrangler secret put GOOGLE_CLIENT_SECRET
|
|
wrangler secret put GITHUB_CLIENT_ID
|
|
wrangler secret put GITHUB_CLIENT_SECRET
|
|
```
|
|
|
|
Passkey is enabled when all three RP values are configured:
|
|
|
|
- `PASSKEY_RP_ID`
|
|
- `PASSKEY_RP_NAME`
|
|
- `PASSKEY_ORIGIN`
|
|
|
|
JWT and bearer token endpoints are disabled by default. Enable them only when an API client needs them:
|
|
|
|
- `ENABLE_JWT=true`
|
|
- `ENABLE_BEARER=true`
|
|
|
|
## Deployment
|
|
|
|
Before deployment, apply migrations to the remote D1 database and deploy the Worker:
|
|
|
|
```bash
|
|
wrangler d1 migrations apply cfw-auth --remote
|
|
pnpm deploy
|
|
```
|
|
|
|
After deploy, repeat the runtime smoke checks against the production `BETTER_AUTH_URL`.
|
|
|
|
## Performance Validation
|
|
|
|
After deployment, compare p50, p95, and p99 for:
|
|
|
|
- `/api/auth/get-session`
|
|
- `/api/auth/api-key/verify`
|
|
- phone OTP endpoints
|
|
- organization invitation endpoints
|
|
|
|
Enable Cloudflare Smart Placement only after logs show that latency is dominated by D1 or external provider round trips. Evaluate D1 read replication or secondary storage only after the first-stage cache and deferred-update changes are measured in production.
|