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

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.