ADR-0024: community-v2 Supabase 접근(client + 커스텀 JWT 발급)을 공용 leaf 패키지 supabase-auth로 둔다
- Status: Accepted
- Date: 2026-10-21
- 관련: HMH-10162 (web 채팅 이관 web-0) · ADR-0023 (DM 신원 서버결정·데이터/제어 2평면) · ADR-0022 (community-v2 Supabase 브랜칭)
Context
community-v2 Supabase 프로젝트 하나를 여러 feature가 공유한다 — 채팅, 총회(assembly OTP·출석 realtime), 리셉션(reception-session). 모두 동일 URL/ANON key/JWT secret을 쓴다(동일 프로젝트). RLS 접근의 공통 전제는 두 가지다: 인증된 client 획득(createClient + accessToken 콜백)과 커스텀 JWT 서명(signSupabaseJWT, app_user_id claim으로 RLS가 actor 검증).
문제는 이 공통 코드가 흩어져 있었다는 것이다. client factory·토큰 fetch는 dashboard features/community-v2/lib/supabase.ts에, signSupabaseJWT는 dashboard와 apps/api(native Bearer용)에 2벌 중복돼 있었다. 보안 인증 코드의 중복은 secret 로테이션·claim 변경 시 한쪽만 바뀌는 드리프트를 낳는다.
웹 채팅 통합 이관(web-0)에서 apps/app도 같은 접근이 필요해졌다. 그대로 복제하면 3벌이 된다. 그렇다고 채팅 패키지(chat-react/chat-core)에 넣으면, 채팅과 무관한 assembly·reception이 채팅 패키지에 의존하게 된다 — web-1(HMH-10161)에서 막 제거한 크로스 결합을 다른 형태로 재생성하는 셈이다. “그때 몰랐던 것”: 이 인증이 채팅 전용이 아니라 community-v2 프로젝트 공용 인프라라는 점을 조사 전엔 과소평가했다.
검토한 대안
| 대안 | 채택 안 한 이유 |
|---|---|
| chat-react에 넣기 | assembly·reception이 채팅 패키지에 역결합(web-1에서 제거한 크로스 결합 재생성). 총회 인증을 “채팅 코드”로 두는 건 의미도 틀림 |
| chat-core에 넣기 | chat-core는 채팅 데이터레이어(client 주입형, platform-agnostic)라, server JWT 서명·web client factory는 결이 다름. “chat” 네이밍도 총회·리셉션에 부정확 |
| 각 feature에 복제 | 인증 비밀 코드의 중복 드리프트 — 지금 이 상황(signSupabaseJWT 2중복)이 바로 그 결과다. “공유 극대화” 목표와 정반대 |
| 총회 데이터를 즉시 별 Supabase 프로젝트로 분리 | 범위 과대·지금 불필요. 단일 프로젝트 전제가 아직 유효하고, 중립 패키지가 미래 분리를 막지 않음(분리 시 해당 feature가 의존만 끊으면 됨) |
Decision
신규 leaf 패키지 @howmuchhome-web/supabase-auth 를 만들어 community-v2 Supabase 접근의 단일 소스로 삼는다. client/server를 entry로 분리해 서버 전용 코드(secret·node:crypto)가 클라 번들에 새지 않게 한다.
- client entry (
.,'use client'):getSupabaseClient(createClient + accessToken),fetchSupabaseAccessToken. - server entry (
./server, React 없음):signSupabaseJWT·SupabaseJWTPayload,handleSupabaseTokenRequest(쿠키UserAPI.getMe→ 서명 → NextResponse; reception의 station_id·token_epoch 같은 선택 claim도 지원). - 소비처 전면 단일화: dashboard 채팅·assembly·reception, apps/app이 모두 이 패키지에서 import. dashboard
features/community-v2/lib의supabase.ts·signSupabaseJWT는 제거. - 심볼만 중립화(
getCommunityV2Supabase→getSupabaseClient등). env(COMMUNITY_V2_SUPABASE_*)·라우트 경로(/api/community-v2/supabase-token)는 레거시 유지 — Vercel env·클라 호출 경로를 바꾸는 리스크를 피한다. - 파일:
packages/supabase-auth/{index.ts,server.ts,signSupabaseJWT.ts}, 각 앱app/api/community-v2/supabase-token/route.ts(공유 핸들러 얇은 wrapper).
apps/api의 native Bearer용 signSupabaseJWT는 당장 통합하지 않는다 — 인증 흐름이 쿠키가 아닌 Bearer라 관심사가 달라, 범위를 web으로 한정한다.
Consequences
좋아지는 것
- community-v2 Supabase 인증이 단일 소스(client + JWT) — secret 로테이션·claim 변경을 1곳에서. dashboard의 2중복 제거.
- apps/app이 복제 없이 즉시 채택 → web 채팅 통합(web-2)의 인증 기반이 선다.
- 채팅·총회·리셉션이 채팅 패키지 결합 없이 중립 leaf 하나에만 의존.
감수하는 것
- 패키지 1개 추가(의존 그래프 노드). client/server entry 분리 규율을 지켜야 한다(서버 코드 클라 번들 누수 방지).
- apps/api native
signSupabaseJWT는 여전히 별도(완전 단일화 아님) — 의도적 범위 분리라 중복 1쌍이 남는다. - env·라우트 이름이 여전히 “community-v2” 레거시라 이름과 실제 범위(총회·리셉션 포함)의 불일치가 코드 밖에 남는다(심볼만 중립화).
이 결정을 다시 열어야 할 때
- 총회/리셉션이 별도 Supabase 프로젝트로 분리되면(데이터 소유 분리), 해당 feature는 이 패키지 의존을 끊고 자기 auth를 갖는다.
- apps/api native 인증까지 단일화하려면 server entry를 Bearer/cookie 양쪽 지원하도록 확장한다.
- Supabase 프로젝트가 여럿이 되면 패키지를 프로젝트별로 나누거나 멀티-client를 지원한다.