devlyn-cli 0.5.1 → 0.5.3

package/bin/devlyn.js

@@ -70,6 +70,7 @@ const OPTIONAL_ADDONS = [
   { name: 'prompt-engineering', desc: 'Claude 4 prompt optimization using Anthropic best practices', type: 'local' },
   { name: 'better-auth-setup', desc: 'Production-ready Better Auth + Hono + Drizzle + PostgreSQL auth setup', type: 'local' },
   { name: 'pyx-scan', desc: 'Check whether an AI agent skill is safe before installing', type: 'local' },
+  { name: 'dokkit', desc: 'Document template filling for DOCX/HWPX — ingest, fill, review, export', type: 'local' },
   // Local optional commands (copied to .claude/commands/)
   { name: 'devlyn.pencil-sync', desc: 'Sync designs between codebase and Pencil (.pen files) via MCP', type: 'command' },
   // External skill packs (installed via npx skills add)

package/optional-skills/better-auth-setup/SKILL.md

@@ -1,22 +1,30 @@
 ---
 name: better-auth-setup
 description: >
-  Production-ready Better Auth integration for Bun + Hono + Drizzle + PostgreSQL projects.
-  Sets up email/password auth, session cookies, API key auth, organization/multi-tenant support,
-  email verification, CORS, security headers, auth middleware, tenant context, and test infrastructure
-  in one pass with zero gotchas. Use this skill whenever setting up authentication in a new
-  Hono/Bun project, adding Better Auth to an existing project, or when the user mentions Better Auth,
-  auth setup, login, signup, session management, API keys, or multi-tenant auth. Also use when
-  debugging auth issues in a Hono + Better Auth stack.
+  Production-ready Better Auth integration for fullstack projects. Covers both the backend
+  (Bun + Hono + Drizzle + PostgreSQL) and the frontend reverse proxy architecture (Next.js,
+  Cloudflare Workers, or any framework proxying auth requests to a separate backend). Sets up
+  email/password auth, session cookies, OAuth providers (Google, GitHub), API key auth,
+  organization/multi-tenant support, email verification, CORS, security headers, auth middleware,
+  tenant context, proxy forwarding headers, dynamic baseURL with allowedHosts, cookie prefix
+  handling, and test infrastructure — all in one pass with zero gotchas. Use this skill whenever
+  setting up Better Auth, adding OAuth/social login, configuring a reverse proxy for auth,
+  debugging redirect_uri_mismatch errors, fixing state_mismatch cookie issues, session cookies
+  not persisting after OAuth callback, or when the user mentions Better Auth, OAuth proxy,
+  auth setup, login, signup, session management, API keys, multi-tenant auth, or
+  "session cookie not working".
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash
-argument-hint: "[new-project-path or 'debug']"
+argument-hint: "[new-project-path | 'debug' | 'proxy']"
 ---
 
 # Better Auth Production Setup
 
-Set up a complete, production-hardened authentication system using Better Auth with Bun + Hono + Drizzle ORM + PostgreSQL. This skill incorporates lessons from real production deployments where each "gotcha" caused hours of debugging.
+Set up a complete, production-hardened authentication system using Better Auth. This skill covers two deployment architectures:
 
-The setup produces a dual-auth system: session cookies for browser users and API keys for programmatic access, with multi-tenant organization support and plan-based access control.
+1. **Backend-only** — Better Auth running directly in a Hono + Bun + Drizzle + PostgreSQL API server
+2. **Fullstack with proxy** — A separate frontend (e.g., Next.js on Cloudflare Workers) that proxies auth requests to the backend
+
+The setup produces a dual-auth system: session cookies for browser users and API keys for programmatic access, with multi-tenant organization support and plan-based access control. Every configuration choice addresses a real production gotcha that caused hours of debugging.
 
 ## Reference Files
 
@@ -27,17 +35,35 @@ Read these when each step directs you to them:
 - `${CLAUDE_SKILL_DIR}/references/api-keys.md` — Key generation, CRUD routes, security patterns
 - `${CLAUDE_SKILL_DIR}/references/config-and-entry.md` — Env config, error types, entry point wiring
 - `${CLAUDE_SKILL_DIR}/references/testing.md` — Test preload, seed factory, integration patterns
+- `${CLAUDE_SKILL_DIR}/references/proxy-setup.md` — Reverse proxy architecture, forwarding headers, OAuth callback routing
+- `${CLAUDE_SKILL_DIR}/references/proxy-gotchas.md` — Proxy-specific troubleshooting (redirect_uri_mismatch, state_mismatch, cookie prefix issues)
 
 ## Handling Input
 
 Parse `$ARGUMENTS` to determine the mode:
 
-- **Empty or project path**: Run the full setup workflow (Steps 1-11)
+- **Empty or project path**: Detect architecture, then run the full setup workflow
 - **`debug`**: Skip to the verification checklist (Step 11) to diagnose an existing setup
+- **`proxy`**: Skip to proxy-specific steps (Steps 12-14) for an existing backend
 - **Specific step number** (e.g., `step 3`): Jump to that step for targeted work
 
 If `$ARGUMENTS` is empty, ask the user for the project path or confirm the current directory.
 
+## Step 0: Detect Architecture
+
+Before starting, determine the deployment architecture:
+
+1. Check if the project has a **separate frontend** that proxies to the backend (look for Next.js, proxy routes, `API_URL` env vars)
+2. Check if the **current project IS the backend** (Hono, Express, or similar server framework with Better Auth)
+
+| Architecture | Signals | Steps |
+|---|---|---|
+| Backend-only | Hono/Express project, no frontend proxy | Steps 1-11 |
+| Frontend proxy (setting up frontend) | Next.js/Remix project with `API_URL` pointing to a backend | Steps 12-14 |
+| Fullstack (both) | Both projects accessible | Steps 1-14 |
+
+If uncertain, ask the user which architecture they're using.
+
 ---
 
 ## Workflow
@@ -111,6 +137,9 @@ export const auth = betterAuth({
   // Always set basePath explicitly — missing this causes route mismatches
   // between where Hono mounts auth routes and where Better Auth handles them.
   basePath: "/auth",
+
+  // For backend-only: use a static baseURL.
+  // For proxy architecture: use allowedHosts (see Step 12).
   baseURL: config.BETTER_AUTH_URL,
   secret: config.BETTER_AUTH_SECRET,
 
@@ -414,8 +443,163 @@ Always append a unique suffix (UUID slice or timestamp) to prevent collisions.
 
 ---
 
+---
+
+## Proxy Architecture (Steps 12-14)
+
+These steps apply when the frontend is a separate application that proxies auth requests to the backend. Read `${CLAUDE_SKILL_DIR}/references/proxy-setup.md` for the complete guide with code examples.
+
+### Step 12: Configure Dynamic baseURL on Backend
+
+**Entry:** Backend auth works directly (Steps 1-11 complete or existing backend).
+**Exit:** Backend derives baseURL per-request from forwarded headers.
+
+Replace the static `baseURL` in `src/lib/auth.ts` with `allowedHosts`:
+
+```typescript
+export const auth = betterAuth({
+  baseURL: {
+    allowedHosts: [
+      "your-frontend.com",      // Frontend domain (via proxy)
+      "your-backend.fly.dev",   // Backend domain (direct access)
+      "localhost",              // Local development
+      "*.fly.dev",              // Platform internal routing
+    ],
+    fallback: process.env.BETTER_AUTH_URL,
+  },
+  basePath: "/auth",
+  advanced: {
+    trustedProxyHeaders: true,  // Read X-Forwarded-Host from the proxy
+  },
+  // ... rest of config unchanged
+});
+```
+
+**Why `allowedHosts` instead of a static baseURL:**
+- A static `baseURL` caches on first request (often a health check with internal hostname)
+- `trustedProxyHeaders: true` alone does NOT work when `baseURL` is set — the static value takes precedence
+- The `BETTER_AUTH_URL` env var also overrides forwarded headers
+- `allowedHosts` derives baseURL per-request and never caches
+
+Add Google OAuth (or other social providers):
+
+```typescript
+socialProviders: {
+  google: {
+    clientId: process.env.GOOGLE_CLIENT_ID!,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+  },
+},
+```
+
+---
+
+### Step 13: Configure Frontend Proxy
+
+**Entry:** Backend uses `allowedHosts` with `trustedProxyHeaders`.
+**Exit:** Frontend proxies auth requests and OAuth callbacks correctly.
+
+The frontend proxy must do three things. Read `${CLAUDE_SKILL_DIR}/references/proxy-setup.md` for complete code.
+
+#### 13a. Create two proxy routes
+
+| Frontend Route | Backend Route | Purpose |
+|---|---|---|
+| `/api/auth/*` | `/auth/*` | Auth-client API calls (browser) |
+| `/auth/*` | `/auth/*` | OAuth callbacks (Google redirects here) |
+
+The second route is critical — Better Auth constructs OAuth callback URLs from `{baseURL}{basePath}/callback/{provider}`. When it derives baseURL from the frontend origin, the callback becomes `https://your-frontend.com/auth/callback/google`.
+
+#### 13b. Set forwarding headers (not just strip them)
+
+```typescript
+// Strip user-provided headers to prevent spoofing
+headers.delete("x-forwarded-for");
+headers.delete("x-forwarded-host");
+headers.delete("x-forwarded-proto");
+headers.delete("x-real-ip");
+headers.delete("cf-connecting-ip");
+
+// Then set correct values from the actual request
+headers.set("x-forwarded-host", url.host);
+headers.set("x-forwarded-proto", url.protocol.replace(":", ""));
+```
+
+#### 13c. Rewrite Location headers
+
+When the backend returns a redirect, rewrite the `Location` header to point to the frontend origin.
+
+---
+
+### Step 14: Configure Frontend Middleware
+
+**Entry:** Proxy routes working.
+**Exit:** Middleware detects session cookies correctly, including `__Secure-` prefix.
+
+In production with HTTPS, Better Auth adds a `__Secure-` prefix to cookie names. Your middleware MUST check for both:
+
+```typescript
+const SESSION_COOKIES = [
+  "__Secure-better-auth.session_token",  // Production (HTTPS)
+  "better-auth.session_token",            // Development (HTTP)
+];
+
+const hasSession = SESSION_COOKIES.some(
+  (name) => !!request.cookies.get(name)?.value,
+);
+```
+
+This is the most insidious gotcha in the proxy architecture — OAuth completes successfully, session is created, cookie is set, but the frontend middleware doesn't recognize it because it only checks the unprefixed name.
+
+Configure the OAuth provider (Google Console example):
+- **Authorized JavaScript origins**: `https://your-frontend.com`
+- **Authorized redirect URIs**: `https://your-frontend.com/auth/callback/google`
+
+The redirect URI uses `/auth/callback/google`, NOT `/api/auth/callback/google`.
+
+---
+
+### Step 15: Verify Proxy Setup
+
+In addition to the Step 11 checklist, verify:
+
+**Proxy**
+- [ ] Proxy route exists at `/api/auth/*` (for auth-client API calls)
+- [ ] Proxy route exists at `/auth/*` (for OAuth callbacks)
+- [ ] Proxy strips THEN sets `X-Forwarded-Host` and `X-Forwarded-Proto`
+- [ ] Proxy rewrites `Location` headers from backend origin to frontend origin
+
+**Dynamic baseURL**
+- [ ] Backend uses `allowedHosts` (not a static `baseURL` string)
+- [ ] `allowedHosts` includes frontend domain, backend domain, and `localhost`
+- [ ] `fallback` is set for health checks
+- [ ] `trustedProxyHeaders: true` is in `advanced` config
+
+**OAuth**
+- [ ] Google Console redirect URI is `https://{frontend}/auth/callback/google`
+- [ ] Verification curl returns `redirect_uri` with frontend domain (not backend)
+
+**Cookies**
+- [ ] Middleware checks both `__Secure-better-auth.session_token` and `better-auth.session_token`
+
+Test with:
+```bash
+curl -s -X POST "https://your-frontend.com/api/auth/sign-in/social" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"google","callbackURL":"/dashboard"}' | \
+  python3 -c "import sys,json,urllib.parse; data=json.load(sys.stdin); url=data.get('url',''); params=urllib.parse.parse_qs(urllib.parse.urlparse(url).query); print('redirect_uri:', params.get('redirect_uri',['N/A'])[0])"
+```
+
+Expected: `redirect_uri: https://your-frontend.com/auth/callback/google`
+
+For detailed troubleshooting of proxy-specific failures, read `${CLAUDE_SKILL_DIR}/references/proxy-gotchas.md`.
+
+---
+
 ## Quick Reference: Common Mistakes
 
+### Backend Mistakes
+
 | Mistake | Consequence | Prevention |
 |---------|-------------|------------|
 | Missing `basePath` | Auth routes 404 | Set `basePath: "/auth"` explicitly |
@@ -428,6 +612,18 @@ Always append a unique suffix (UUID slice or timestamp) to prevent collisions.
 | Generic 403 for no org | Frontend can't show helpful UX | Distinct `no_organization` code |
 | `credentials: true` + `*` | Browser rejects response | Specific origins with credentials |
 
+### Proxy Mistakes
+
+| Mistake | Consequence | Prevention |
+|---------|-------------|------------|
+| Static `baseURL` with proxy | OAuth callback uses wrong domain | Use `allowedHosts` + `fallback` |
+| `trustedProxyHeaders` without `allowedHosts` | Static baseURL or env var overrides | `allowedHosts` bypasses priority chain |
+| Only `/api/auth/*` proxy route | OAuth callback 404 (Google redirects to `/auth/callback/*`) | Add `/auth/*` proxy route |
+| Proxy only strips headers | Backend doesn't know frontend origin | Strip THEN set `X-Forwarded-Host` |
+| Middleware checks only `better-auth.session_token` | Authenticated users redirected to sign-in | Check both `__Secure-` prefixed and plain |
+| Google Console redirect URI with `/api/auth/` | `redirect_uri_mismatch` from Google | Use `/auth/callback/google` (not `/api/auth/`) |
+| `BETTER_AUTH_URL` env var set | Overrides forwarded headers | Use `allowedHosts` with `fallback` instead |
+
 <example>
 **User**: "Set up Better Auth in my new Hono project at ./my-api"
 
@@ -448,3 +644,18 @@ Always append a unique suffix (UUID slice or timestamp) to prevent collisions.
 14. Create test utilities (setup.ts, db.ts, app.ts)
 15. Run verification checklist
 </example>
+
+<example>
+**User**: "I have a Next.js frontend and Hono backend. I need Google OAuth working through the proxy."
+
+**Steps taken**:
+1. Detect proxy architecture (Step 0)
+2. Update backend auth.ts: replace static baseURL with allowedHosts + trustedProxyHeaders (Step 12)
+3. Add Google social provider to auth config (Step 12)
+4. Create /api/auth/* and /auth/* proxy routes on frontend (Step 13)
+5. Set forwarding headers in proxy (Step 13)
+6. Add Location header rewriting (Step 13)
+7. Update frontend middleware to check both cookie names (Step 14)
+8. Configure Google Console redirect URI (Step 14)
+9. Run proxy verification checklist (Step 15)
+</example>

package/optional-skills/better-auth-setup/references/proxy-gotchas.md

@@ -0,0 +1,148 @@
+# Better Auth + Reverse Proxy — Gotchas & Troubleshooting
+
+Common failures when running Better Auth behind a reverse proxy, with root causes and fixes. Each gotcha was discovered through real debugging — they are not obvious from the docs.
+
+## Table of Contents
+
+1. [redirect_uri_mismatch from Google](#1-redirect_uri_mismatch-from-google)
+2. [state_mismatch after OAuth callback](#2-state_mismatch-after-oauth-callback)
+3. [404 on all auth endpoints](#3-404-on-all-auth-endpoints)
+4. [Session cookie not detected after login](#4-session-cookie-not-detected-after-login)
+5. [trustedProxyHeaders not working](#5-trustedproxyheaders-not-working)
+6. [baseURL caches wrong origin](#6-baseurl-caches-wrong-origin)
+7. [BETTER_AUTH_URL env var overrides everything](#7-better_auth_url-env-var-overrides-everything)
+8. [OAuth callback hits backend directly (skips proxy)](#8-oauth-callback-hits-backend-directly-skips-proxy)
+
+---
+
+## 1. redirect_uri_mismatch from Google
+
+**Symptom**: Google OAuth returns `redirect_uri_mismatch` error page.
+
+**Root cause**: The `redirect_uri` Better Auth sends to Google doesn't match what's configured in Google Console. This happens when Better Auth derives the wrong baseURL — typically the backend's domain instead of the frontend's.
+
+**Debug**: Run the verification curl to see what `redirect_uri` is actually being sent:
+```bash
+curl -s -X POST "https://your-frontend.com/api/auth/sign-in/social" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"google","callbackURL":"/dashboard"}' | \
+  python3 -c "import sys,json,urllib.parse; data=json.load(sys.stdin); url=data.get('url',''); params=urllib.parse.parse_qs(urllib.parse.urlparse(url).query); print('redirect_uri:', params.get('redirect_uri',['N/A'])[0])"
+```
+
+Compare the output to Google Console's "Authorized redirect URIs".
+
+**Fix**:
+- Ensure `allowedHosts` includes the frontend domain
+- Ensure the proxy sets `X-Forwarded-Host` header (not just strips it)
+- Ensure `trustedProxyHeaders: true` is in the `advanced` config
+- Google Console redirect URI must be `https://{frontend}/auth/callback/{provider}` — note `/auth/`, NOT `/api/auth/`
+
+**Google Console propagation**: Changes take up to 5 minutes. If you just updated, wait and retry.
+
+---
+
+## 2. state_mismatch after OAuth callback
+
+**Symptom**: After Google redirects back, Better Auth returns a `state_mismatch` error, typically visible at the backend URL.
+
+**Root cause**: The state cookie was set on the frontend domain during OAuth initiation, but the callback arrived directly at the backend domain. Different domain = no cookie = state mismatch.
+
+**Fix**: The OAuth callback URL must route through the frontend proxy, not directly to the backend. This means:
+1. A proxy route at `/auth/*` must exist on the frontend (in addition to `/api/auth/*`)
+2. The `redirect_uri` sent to the OAuth provider must use the frontend domain
+3. Both the initial request and callback must share the same domain for cookies to work
+
+**How to verify**: Check the `redirect_uri` in the OAuth initiation response. If it points to the backend domain, the `allowedHosts` or forwarding headers are misconfigured.
+
+---
+
+## 3. 404 on all auth endpoints
+
+**Symptom**: POST `/api/auth/sign-in/social` (or any auth endpoint) returns 404.
+
+**Root causes** (multiple possible):
+
+### 3a. baseURL includes a path component
+Setting `baseURL` to something like `https://frontend.com/api` breaks Better Auth's internal routing. Better Auth uses `basePath` for path prefixing — `baseURL` should only be the origin (protocol + host).
+
+### 3b. Host mismatch with static baseURL
+If `baseURL` is `https://frontend.com` but requests arrive at the backend with `Host: backend.fly.dev`, Better Auth may reject the request because the host doesn't match. This is why dynamic `allowedHosts` is needed.
+
+### 3c. allowedHosts array is empty or malformed
+If the `allowedHosts` array doesn't match any incoming host AND no `fallback` is set, Better Auth has no baseURL to work with and may reject requests.
+
+### 3d. Missing proxy route
+If only `/api/auth/*` is proxied but the request arrives at `/auth/*` (OAuth callback), there's no route handler.
+
+**Fix**: Use `allowedHosts` with all known domains, always set `fallback`, and ensure both proxy routes exist.
+
+---
+
+## 4. Session cookie not detected after login
+
+**Symptom**: OAuth completes successfully (no Google errors, callback returns 302 to `/dashboard`), but the user is immediately redirected to `/sign-in?redirect=%2Fdashboard`.
+
+**Root cause**: In production with HTTPS, Better Auth prefixes cookie names with `__Secure-`. The cookie is actually named `__Secure-better-auth.session_token`, not `better-auth.session_token`. If middleware only checks the unprefixed name, it never finds the cookie.
+
+**Why it happens with allowedHosts**: When `baseURL` is a dynamic config object (not a string), Better Auth can't determine the protocol at initialization time. In production (`NODE_ENV=production`), it defaults to secure cookies with the `__Secure-` prefix.
+
+**Fix**: Middleware must check both cookie names:
+```typescript
+const SESSION_COOKIES = [
+  "__Secure-better-auth.session_token",
+  "better-auth.session_token",
+];
+```
+
+**This is the most insidious gotcha** because everything appears to work — OAuth succeeds, session is created, cookie is set — but the frontend doesn't recognize it. Without the skill, Claude diagnoses this as "Set-Cookie header stripping" (plausible but wrong) instead of the `__Secure-` prefix (correct).
+
+---
+
+## 5. trustedProxyHeaders not working
+
+**Symptom**: Despite setting `trustedProxyHeaders: true`, Better Auth still uses the wrong origin for callback URLs.
+
+**Root cause**: `trustedProxyHeaders` only takes effect when Better Auth actually reads forwarded headers. The `getBaseURL()` function has a priority order:
+1. Static `baseURL` string (if set) — **always wins**
+2. `BETTER_AUTH_URL` environment variable — **checked before headers**
+3. `X-Forwarded-Host` / `X-Forwarded-Proto` headers — only reached if 1 and 2 are absent
+4. Request URL — last resort
+
+**Fix**: Use `allowedHosts` instead. It explicitly reads `X-Forwarded-Host` and constructs the baseURL per-request, bypassing the priority chain entirely.
+
+---
+
+## 6. baseURL caches wrong origin
+
+**Symptom**: Auth works for the first request after deploy, then breaks. Or auth never works because the first request was a health check.
+
+**Root cause**: When using a static `baseURL` string or `trustedProxyHeaders` without `allowedHosts`, Better Auth resolves the baseURL once from the first request and caches it. If the first request is a health check (which arrives with `Host: backend.internal`), all subsequent requests use that cached value.
+
+**Fix**: Use `allowedHosts` — it derives baseURL per-request and never caches.
+
+---
+
+## 7. BETTER_AUTH_URL env var overrides everything
+
+**Symptom**: You removed `baseURL` from the config to let `trustedProxyHeaders` work, but Better Auth still uses the wrong origin.
+
+**Root cause**: Better Auth's `getBaseURL()` checks the `BETTER_AUTH_URL` environment variable before checking forwarded headers. If this env var is set (e.g., as a Fly.io secret), it takes precedence.
+
+**Fix**: Either:
+- Remove the `BETTER_AUTH_URL` env var entirely (risky — health checks need it)
+- Use `allowedHosts` with `fallback: process.env.BETTER_AUTH_URL` — this bypasses the internal env var check while still having a fallback for non-proxied requests
+
+---
+
+## 8. OAuth callback hits backend directly (skips proxy)
+
+**Symptom**: After Google OAuth, the browser lands on `https://backend.fly.dev/auth/callback/google` instead of going through the frontend proxy.
+
+**Root cause**: Better Auth constructed the callback URL using the backend's origin instead of the frontend's. This means the forwarding headers weren't set correctly, or `allowedHosts` didn't match the frontend domain.
+
+**Fix**:
+1. Verify the proxy sets `X-Forwarded-Host: frontend.com` (not just strips headers)
+2. Verify `allowedHosts` includes `frontend.com`
+3. Use the curl verification command to check what `redirect_uri` is being generated
+
+**Quick debug**: The most common cause is that the proxy strips forwarding headers but doesn't set new ones. The proxy must do both: strip (prevent spoofing) then set (tell backend the real origin).