다크모드
로그인 계약 — BE 참고 매뉴얼
범위
이 문서는 Leyve 로그인 화면이 요구하는 인증 계약을 설명합니다. 현재 레포는 Supabase로 동작을 검증하는 프로토타입이며, 실서비스 AWS + RDS MariaDB 구현에서도 아래 문맥·식별자·보안 불변식을 유지해야 합니다. Supabase 테이블 구조나 RLS를 목표 아키텍처로 간주하지 않습니다.
인증 경로
| 로그인 문맥 | 식별자 유형 | 사용자 입력 |
|---|---|---|
| Organization | EMAIL | 이메일 + 패스워드 |
| Organization | ORGANIZATION_LOGIN_ID | 조직 코드 + 로그인 ID + 패스워드 |
| Workspace | WORKSPACE_LOGIN_ID | 워크스페이스 코드 + 로그인 ID + 패스워드 |
FE는 세 경로를 iam-login 계약으로 전달합니다. 프로토타입 adapter는 src/composables/iamAuthRepo.js, companyAuthRepo.js, workforceAuthRepo.js에 있습니다. 로그인 화면의 대상 사용자·운영자 포털 설명 문구는 API 계약이 아니며 화면에 노출하지 않습니다. 로그인 문맥과 식별자 유형은 route와 요청 payload로 명시합니다.
로그인 ID는 전역 고유일 필요가 없습니다. 저장·조회 시에는 정규화된 {login_id}@{organization_code} 또는 {login_id}@{workspace_code} 복합 식별자를 사용해 코드가 다른 영역에서 같은 로그인 ID를 허용합니다. 복합 식별자는 사용자 UI에 노출하지 않습니다.
정규화와 검증
- 이메일: trim + lowercase
- 조직 코드:
org-+ Crockford 계열 10자 - 워크스페이스 코드:
ws-+ Crockford 계열 10자 - 로그인 ID: 영문·숫자로 시작/종료하고 내부에
.,_,-허용 - 코드와 로그인 ID: trim + lowercase
FE 정규식은 빠른 입력 안내일 뿐 보안 경계가 아닙니다. API가 같은 규칙을 다시 검증하고, 조직/워크스페이스 활성 상태와 principal·affiliation·membership 유효기간을 확인해야 합니다. 레거시 무접두 워크스페이스 코드는 허용하지 않으며 FE와 API 모두 ws- 형식을 검사합니다.
세션과 인가 불변식
- 로그인 방법은 principal을 찾는 수단일 뿐 role이나 권한을 부여하지 않습니다.
- Organization 로그인은 Organization affiliation 범위를, Workspace 로그인은 해당 Workspace membership 범위를 세션 문맥으로 확정합니다.
- 한 principal이 여러 Workspace membership을 가질 수 있습니다.
- Workspace 로그인 후 다른 접근 가능한 Workspace로 이동할 수 있더라도, 매 요청에서 대상 membership과 role assignment를 다시 검사합니다.
- Platform Administrator 로그인은 고객 로그인 계약에 포함하지 않으며 별도 issuer/portal을 사용합니다.
- 인증 실패 응답은 사용자·코드 존재 여부를 구별하지 않습니다.
패스워드 복구
- Organization 이메일 계정: 검증된 이메일 recovery를 사용할 수 있습니다.
- Organization 로그인 ID: 현재는 조직 관리자에게 재설정을 요청합니다.
- Workspace 로그인 ID: 현재는 워크스페이스 관리자에게 재설정을 요청합니다.
ID 계정의 self-service 복구를 추가할 때는 별도 본인 확인 수단, 일회성 토큰, 만료, 재사용 방지, 모든 세션 폐기, 최초 로그인 시 변경 강제를 상태머신으로 정의해야 합니다. 관리자가 기존 패스워드를 조회하거나 전달하는 API는 만들지 않습니다.
오류 계약
FE에 반환하는 메시지는 다음 원칙을 지킵니다.
조직 코드, 로그인 ID 또는 패스워드를 확인해 주세요.워크스페이스 코드, 로그인 ID 또는 패스워드를 확인해 주세요.로그인 세션을 시작하지 못했습니다.
DB 키, 내부 이메일, Auth provider 원문 오류, principal 존재 여부는 응답이나 로그에 노출하지 않습니다. 패스워드와 recovery token은 애플리케이션 로그·감사 이벤트·분석 payload에 기록하지 않습니다.
Supabase 프로토타입 배포 계약
iam-login과 iam-context는 호스팅 환경의 기본 시크릿인 SUPABASE_PUBLISHABLE_KEYS, SUPABASE_SECRET_KEYS JSON dictionary에서 default 키를 사용합니다. 로컬·레거시 환경에서만 단일 키 변수로 fallback합니다. 시크릿 값이나 키 dictionary를 로그에 기록하지 않습니다.
로그인 전에는 authenticated 사용자 문맥이 없으므로 Edge Function의 secret key가 service_role로 IAM 테이블을 조회합니다. 마이그레이션은 조회 테이블에 select, 세션 원장에 select, insert, update, 인가 감사 이벤트에 select, insert만 명시적으로 부여합니다. RLS 우회 여부와 별개로 PostgreSQL table privilege가 필요하며, 권한 누락은 일반 자격 증명 오류로 숨기지 말고 서버 로그에서 운영 설정 결함으로 관측해야 합니다.