# 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.