cfw-auth/docs/auth-operations.md

cfw-auth account center operations

Local development

Install dependencies once:

pnpm install

Apply local D1 migrations:

pnpm db:apply:local

Start the Worker:

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:

pnpm exec wrangler dev --port 8788

Verification

Run the full local readiness check before deploying:

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:

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:

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:

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:

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:

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:

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.