Kakao Login Live Integration: from KOE006 to KOE010, and the decision to do OAuth directly

Decision: direct OAuth instead of Better Auth

The spec (§16) says "Better Auth + Kakao/Apple, Kakao via generic OAuth". Kakao isn't a first-class BA provider so generic config is needed anyway, and since lib/auth is already a clean interface, I judged direct OAuth (2 routes) to be simpler and more reliable. The shared auth logic is extracted into establishUser(), which dev login and Kakao both use.

• Flow: /api/auth/kakao (state cookie + authorize redirect) → Kakao consent → /api/auth/kakao/callback (verify state → token exchange → user lookup → establishUser('kakao:<id>', nickname) → session cookie → /box).
• Minimal collection: only the Kakao user id + nickname. No email/phone requested (= no business verification required, also better for trust).
• Commits: 8899c09 (implementation), 71db46b (debug logging).

Pre-verification with dummy keys

Before getting the real keys, with dummy keys I checked: the authorize redirect URL/parameters/state cookie, the callback error paths (kakao_denied/state_mismatch), the button visibility condition, and coexistence with dev login.

Real keys — gate 1: KOE006

Admin Settings Issue (KOE006)
An error in the 버팀목 service settings prevents the service from being used.

• Cause (verified): the exact Redirect URI (http://localhost:3000/api/auth/kakao/callback) was not registered in the console. (Kakao docs: "if the redirect URI is incorrect, KOE006".)
• Fix: registered it exactly under console [Platform keys]→[REST API key]→[Redirect URI] + turned Kakao Login ON. (Console setting, no code change.)
• Since the console menu differs from the article's old description, I rechecked the official docs and guided with the current path. (I only read the public docs; I couldn't directly see the user's logged-in console — the blocked screen was confirmed via screenshot.)

Real keys — gate 2: KOE010

The login window and consent passed, but it failed at the callback. At first the cause was unknown, so I added detailed logging (71db46b):

[kakao callback] kakao token exchange 401: {"error":"invalid_client","error_description":"Bad client credentials","error_code":"KOE010"}

• Cause (verified): the app has Client Secret ON but the token request didn't include client_secret. (The REST key is fine — confirmed by the app name "버팀목" rendering + KOE006 already passing.)
• Fix: added KAKAO_CLIENT_SECRET to .env.local (gitignored). kakaoExchangeToken includes it automatically when present.

Success (confirmed via server logs)

GET /api/auth/kakao/callback?code=…&state=… 307 (token exchange 2.2s)
GET /box 200

Created and entered the kakao:<id> box with a real Kakao account. → Achieved the top trust priority, "real, identity-verified ownership".

Pattern

• KOE006 = redirect URI not registered/typo (scheme·host·port·path must be exact, localhost≠127.0.0.1).
• KOE010 invalid_client (after KOE006 is resolved) = Client Secret is ON but not sent.
• Debug external APIs by not guessing but logging the response body — KOE010 was pinpointed immediately with a single logging addition.