보안/접근통제 정책¶
문서 역할¶
- 역할:
규범 - 문서 종류:
policy - 충돌 시 우선 문서: 관리자 역할·최대 접근 범위·인가 기본값은 이 문서, 도메인 상태·행위의 세부 허용 조건은
단일 SoT와 우선순위표의 도메인 정책 - 기준 성격:
transition- 이 문서의 폐쇄형 권한 매트릭스를 최종 기준으로 사용한다.
- 현행 표시·서버 인가와의 차이는
증빙/추적의 기술부채에서 제거 조건을 관리한다.
목적¶
- Super Admin과 일반 클럽매니저의 권한 경계를 하나의 폐쇄형 기준으로 고정한다.
- 인증·인가·UI 표시 책임을 분리해 직접 URL/API 요청을 통한 권한 우회를 차단한다.
적용 범위¶
coupler-api,coupler-admin-web,coupler-mobile-app- 관리자 계정, Admin 메뉴와 API, 운영 액션, 회원·결제·신고 등 민감 데이터의 운영 접근
- Mobile 회원의 서비스 기능 자격과 cron·배치·서비스 계정 권한은 제외한다. 해당 도메인 정책과 실행 주체 계약을 따른다.
단일 SoT와 우선순위¶
| 판정 책임 | 단일 SoT | 이 문서의 역할 | 충돌 해결 순서 |
|---|---|---|---|
| 관리자 역할, 최대 데이터 범위, 기본 거부 | 이 문서 | 최종 규칙 | 이 문서 |
| 회원 심사 상태와 단계별 행위 | 회원 심사 단일 정책 | 역할별 최대 범위 안에서 세부 행위를 좁힘 | 이 문서의 최대 범위 -> 회원 심사 정책 |
| 매칭 대상과 예약 소유 범위 | 매칭 운영 정책 | ASSIGNED·OWNED의 도메인 의미를 구체화 |
이 문서의 최대 범위 -> 매칭 정책 |
| 결제 검증·환불·정산 행위 | 결제 운영 정책 | 역할별 최대 범위 안에서 결제 행위를 좁힘 | 이 문서의 최대 범위 -> 결제 정책 |
| API 실패 응답 | API 에러 계약 정책 | 권한 실패 의미만 소유 | API 에러 정책 |
| 민감정보 분류와 보관 | 데이터 거버넌스 정책 | 최소 권한 원칙만 소유 | 데이터 거버넌스 정책 |
| 공통 Fail-closed와 레이어 책임 | 엔지니어링 가드레일 | 관리자 권한에 구체화 | 엔지니어링 가드레일 -> 이 문서 |
| 구현 구조와 논리 데이터 모델 | 관리자 권한 시스템 | 규범을 정의하지 않는 설명 | 이 문서 |
| 리뷰와 검증 증빙 | 코드 리뷰 정책, 테스트/CI 전략 | 권한별 검증 대상을 제공 | 각 검증 정책 |
- 도메인 정책은 이 문서가 부여한 역할별 최대 범위를 넓힐 수 없고 상태·행위 조건으로 더 좁힐 수만 있다.
- 최종 허용 결과는
이 문서의 역할·범위와도메인 정책의 상태·행위 조건의 교집합이다. 둘 중 하나라도 없거나 충돌하면 거부한다.
관리자 역할과 데이터 범위¶
역할¶
| 역할 ID | 표시명 | 서버 판정 | 유효 조건 |
|---|---|---|---|
SUPER_ADMIN |
Super Admin | 현재 관리자 레코드의 super > 0 |
인증된 관리자 계정 |
CLUB_MANAGER |
일반 클럽매니저 | 현재 관리자 레코드의 super = 0 |
인증된 관리자 ID와 같은 ID의 현재 club-manager.manager가 존재 |
super가 누락됐거나 숫자로 확정되지 않거나 위 두 역할에 매핑되지 않으면 미정의 역할로 거부한다.- 현행 연결은
admin-access.operator와club-manager.manager가 같은 관리자 ID를 사용하는 1:1 관계다. 별도 임시·비활성 연결 상태는 없으며 둘 중 하나가 존재하지 않으면 연결은 유효하지 않다. super = 0이지만 위 연결을 확인할 수 없으면 일반 클럽매니저로 추정하지 않고 거부한다.- JWT의 역할 값은 Admin 표시용 힌트일 뿐 서버 인가 근거가 아니다. API는 인증 후 조회한 현재 관리자 레코드와 도메인 관계로 역할과 범위를 판정한다.
데이터 범위¶
| 범위 ID | 의미 | 판정 원천 |
|---|---|---|
GLOBAL |
해당 Admin 기능군의 모든 허용 데이터 | SUPER_ADMIN 역할과 도메인 상태 |
ASSIGNED |
현재 클럽매니저에게 전담·공유 등으로 배정된 데이터 | 도메인 배정 관계와 도메인 정책 |
OWNED |
현재 클럽매니저 계정이 생성하거나 호스트로 소유한 데이터 | 생성자·호스트 등 도메인 소유 관계 |
SHARED |
역할별 개별 소유자가 없는 공통 기준정보·설정·상태 | 이 문서의 명시적 행위와 도메인 정책 |
SELF |
로그인한 관리자 자신의 계정·세션 데이터 | 인증된 관리자 ID |
NONE |
허용하지 않음 | 기본 거부 |
- 역할, 데이터 범위, 조회·변경 행위는 서로 독립된 축이다.
ASSIGNED조회가 허용돼도 같은 데이터의 모든 변경 행위가 자동으로 허용되지 않는다. - 유효한 역할·연결로 범위 조회를 수행했으나 해당 데이터가 0건이면 빈 목록을 반환할 수 있다. 반면 역할·연결 자체를 확인할 수 없거나 직접 요청한 대상 ID가 배정·소유 범위 밖이면 빈 목록이나 성공 응답으로 바꾸지 않고 권한 실패로 처리한다.
Admin 기능군 권한 매트릭스¶
아래 표는 현재 Admin 기능과 행위의 역할별 최대 권한이다. 관리, 운영 같은 포괄 표현은 권한을 부여하지
않으며, 표에 명시한 행위와 범위의 조합만 허용한다. 세부 상태 조건은 연결된 도메인 정책이 더 좁힐 수 있다.
표의 행 분리는 현재 UI·API 행위를 판정 단위로 풀어쓴 것이며 신규 기능 개발 목록이나 다른 도메인의 추가
정책화 요구가 아니다. 현재 기능이 추가·제거·변경될 때만 이 목록을 바꾼다.
| 기능·행위 | Super Admin | 일반 클럽매니저 | 세부 기준 |
|---|---|---|---|
| 본인 비밀번호·세션 조회·변경 | SELF |
SELF |
이 문서 |
| 관리자·클럽매니저 계정/역할/전체 상세 조회·생성·변경·삭제 | GLOBAL |
NONE |
계정 식별자·인증정보·필수 인증 설정을 포함 |
| 회원의 공유매니저 선택에 필요한 클럽매니저 공개 목록 조회 | SHARED |
SHARED |
cnt, list envelope 안의 각 목록 item은 id, nickname만 허용 |
| 운영 알림·미처리 배지 조회 | 허용된 GLOBAL 기능의 집계 |
ASSIGNED·OWNED로 허용된 기능의 집계 |
다른 역할에 NONE인 기능의 건수는 집계하지 않음 |
| 대시보드와 가입·로그인 등 플랫폼 통계 조회 | GLOBAL |
NONE |
아래 결제·매출 집계 행은 제외 |
| 회원 목록·건수·상태·초대순위·상세와 키/휴면/초대/지인차단/추천사/1:1 매칭 이력 조회 | GLOBAL |
현재 CHARGE 배정 회원의 ASSIGNED |
초대순위는 초대 실행 권한이 아닌 조회 기능 |
| 회원 기본정보·활성 여부·VIP 여부 변경 | GLOBAL |
현재 CHARGE 배정 회원의 ASSIGNED |
대상 ID의 현재 배정을 변경 operation에서 재확인 |
| 회원 프로필 영상 삭제 | GLOBAL |
NONE |
현재 관리자 레코드의 Super Admin 역할을 삭제 transaction에서 재확인; 기존 확인창 외 별도 사유 입력 없음 |
회원의 전담(CHARGE) 클럽매니저 배정 변경 |
GLOBAL |
NONE |
진행 중 매칭 등 변경 금지 조건 확인 |
회원의 공유(SHARE) 클럽매니저 배정 조회·변경 |
GLOBAL |
현재 CHARGE 배정 회원의 ASSIGNED |
일반 클럽매니저는 자신의 전담 회원에 대한 공유 배정만 변경 |
[신청] 일반회원(최초) 목록·상세 조회 |
GLOBAL |
가입 시 선택한 현재 클럽매니저 회원의 ASSIGNED |
회원 심사 단일 정책 |
| 그 외 일반 클럽매니저 허용 심사 단계의 목록·상세 조회 | GLOBAL |
현재 CHARGE 배정 회원의 ASSIGNED |
허용 단계는 회원 심사 단일 정책 |
최종 [심사거절] 목록·상세 조회 |
GLOBAL |
NONE |
회원 심사 단일 정책 |
| 최초 일반회원 신청 승인·거절 | GLOBAL |
NONE |
회원 심사 단일 정책 |
| 최초 신청 이외 심사 단계의 승인·반려 | GLOBAL |
현재 CHARGE 배정 회원의 ASSIGNED |
회원 심사 단일 정책의 단계·상태 조건 적용 |
| 회원의 현재 인증자료 삭제 | GLOBAL |
현재 CHARGE 배정 회원의 ASSIGNED |
대상 인증자료가 해당 회원 소유인지 operation에서 재확인 |
| 무료키 지급 | GLOBAL |
NONE |
정상 회원 조건과 사유·키 이력 기록 적용 |
| 회원 차단·차단 해제·DB 삭제·홀딩 해제·자동 개인정보 파기 정지/해제·추천사 삭제 | GLOBAL |
NONE |
행위별 상태·사유·감사 조건 적용 |
| 클럽매니저 상담 목록·대화 조회·메시지 전송 | GLOBAL |
현재 CHARGE 배정 회원의 ASSIGNED |
조회·전송 operation에서 대상 배정을 재확인 |
| 1:1 매칭 목록/상세/채팅·대상·미사용 카드 건수 조회, 매칭 생성, 큐레이터 제안 거절·연결 | GLOBAL |
매칭 운영 정책의 경로별 ASSIGNED |
시작 회원과 상대 후보의 CHARGE·SHARE 규칙 적용 |
| 1:1 매칭 후기 목록 조회 | GLOBAL |
NONE |
현재 Admin 메뉴에서는 비노출인 기존 API도 같은 범위 적용 |
| 1:1 매칭 삭제·미사용 카드 일괄 삭제·장소 설정 조회/변경 | GLOBAL |
NONE |
이 문서 |
| 매칭 예약 목록 조회·생성·삭제·즉시 발송 | GLOBAL |
현재 로그인 관리자가 생성한 예약의 OWNED |
매칭 운영 정책 |
| 매칭 예약 공통 설정 조회·예약 확정·취소 | SHARED |
SHARED |
매칭 운영 정책의 공통 예약 상태 |
| 1:1 매칭 신고 조회 | GLOBAL |
신고 대상이 현재 CHARGE 배정 회원인 ASSIGNED |
이 문서 |
| 1:1 매칭 후기 환불·신고 처리/환불·회원 제재 | GLOBAL |
NONE |
행위별 상태·사유 조건 적용 |
| 기존 2:2 그룹미팅 조회·변경·신고/패널티 처리 | GLOBAL |
NONE |
이 문서 |
| 클럽 Host N:N 행사 목록/상세·생성·변경·공개 활성 전환·신청 접수 재개·확정·취소·삭제와 상세 이미지 변경 | GLOBAL |
자신이 호스트로 연결된 행사의 OWNED |
상태·version·사유 조건 적용 |
| 클럽 Host N:N 행사 강제삭제 | GLOBAL |
NONE |
DELETED가 아닌 행사만 허용하며 version·필수 사유·감사 이력 조건 적용 |
| 클럽 Host N:N 신청 조회·프로필 열람·승인·확정 취소와 채팅/후기/열람 이력 조회 | GLOBAL |
자신이 호스트로 연결된 행사의 OWNED |
행사 소유와 신청 상태를 operation에서 재확인 |
| 클럽 Host N:N 신고 조회 | GLOBAL |
자신이 호스트로 연결된 행사의 OWNED |
이 문서 |
| 클럽 Host N:N 본인 호스트 연결 정보 조회 | GLOBAL |
SELF |
일반 클럽매니저는 자신의 연결과 행사 생성 가능 여부만 조회 |
| 클럽 Host N:N 호스트 연결 생성·채팅 메시지 운영 삭제·신고 처리·회원 차단/패널티 | GLOBAL |
NONE |
이 문서 |
| 라운지 콘텐츠·댓글·신고·패널티 조회·변경 | GLOBAL |
NONE |
이 문서 |
| 결제 로그·매출 집계·무료키 지급 이력 조회 | GLOBAL |
현재 CHARGE 배정 회원의 ASSIGNED |
결제 운영 정책 |
| 결제 상태 변경·환불 | GLOBAL |
현재 CHARGE 배정 회원 결제의 ASSIGNED |
결제 운영 정책의 상태·사유 조건 적용 |
| 고객센터 문의 조회·답변·삭제 | GLOBAL |
NONE |
이 문서 |
| Admin 화면 표시·선택용 공통 기준정보 조회 | SHARED |
SHARED |
설정 관리가 아니라 화면 렌더링에 필요한 읽기 전용 허용 목록 |
| 앱 버전·설정값·약관·공지·가입 안내 조회·생성·변경·삭제 | GLOBAL |
NONE |
이 문서 |
- 이미지·파일 업로드, 상태 조회, 선택 목록 같은 보조 operation은 독립 권한을 만들지 않는다. 표에서 허용된
상위 행위의 일부로 호출될 때만 같은 역할·대상 범위를 적용하며, 상위 행위를 확인할 수 없으면
NONE이다. - 로그인은 역할별 기능 권한이 아니라 인증 진입점이다. 유효한 관리자 자격증명을 확인한 뒤 보호된 첫 요청부터 현재 역할과 일반 클럽매니저 연결을 판정한다.
- 표에 없는 신규 기능군과 신규 운영 액션은
NONE이다. 권한을 부여하려면 구현 전에 이 표와 해당 도메인 정책을 같은 변경 단위에서 갱신한다. SUPER_ADMIN의GLOBAL은 Admin 기능군의 데이터 범위를 뜻한다. 도메인 상태 전이, 사유 입력, 감사 로그, 멱등성, 개인정보 최소화, 시스템 전용 작업을 우회할 권한이 아니다.
적용 상태와 생명주기¶
| 상태 | 진입 조건 | 허용 구조 | Exit Gate |
|---|---|---|---|
| 권한 SoT 전환 중 | 이 매트릭스와 현행 Admin 표시·API 인가 중 하나 이상이 불일치 | 이 매트릭스를 최종 판정 기준으로 고정하고 기존 차이는 관리자 권한 서버 인가·표시 계약 미정렬에서만 추적; 기존 불일치를 허용 근거로 사용 금지 |
Admin route·API operation 매핑 100%, 직접 우회 0건, 역할·연결·담당/소유별 회귀 테스트 통과 |
| 정상 권한 | 역할·기능군·행위·데이터 범위가 모두 정의됨 | 서버 인가 후 허용 범위만 처리, UI는 결과를 표시 | 권한별 허용·거부 테스트 통과 |
| 미정의/불일치 | 역할·기능군·행위·범위 중 하나가 없거나 서로 충돌 | 즉시 거부와 구조화 실패 로그만 허용 | 정책·코드·테스트를 함께 정의하기 전까지 허용 금지 |
| 권한 변경 | 역할 또는 관리자-클럽매니저 연결이 변경됨 | 감사 이력, 서버의 현재값 즉시 적용, Admin 세션 표시 갱신 | 구 권한 요청 거부와 신 권한 허용 검증 |
| 임시 권한 | 운영상 한시적 예외가 필요함 | 현재 2역할 모델에서는 허용하지 않음 | 별도 operation-scoped grant, 담당자·만료·회수·감사 설계가 정책과 코드에 먼저 반영돼야 함 |
필수 규칙¶
인증·인가 책임 분리¶
- 인증은 토큰/세션 검증 미들웨어에서 수행하고, 인가는 API 서버의 operation 경계에서 수행한다.
- Admin의 메뉴·버튼·route 숨김은 표시 제어다. 직접 URL과 API 요청은 동일한 서버 인가를 통과해야 한다.
- 상위 메뉴 권한은 하위 route에 자동 상속된다고 가정하지 않는다. 렌더 가능한 모든 route와 호출 가능한 모든 API operation을 독립적으로 검증한다.
- 목록 필터만으로 변경 권한을 증명하지 않는다. 상세·변경·삭제 operation은 대상 ID의
ASSIGNED또는OWNED관계를 서버에서 다시 확인한다.
운영 액션 통제¶
- 승인·반려·제재·무료키 지급·환불·삭제 등 중요 액션은 사유를 필수로 받고 역할·범위·도메인 상태를 모두 확인한다.
- 중요 액션은
actor,target,reason,timestamp와 영속 감사 레코드 식별자를 기록한다. - 권한 부여·회수와 관리자-클럽매니저 연결 변경은 변경 전/후 값과 행위자를 감사 이력으로 남긴다.
- 회원 프로필 영상 삭제는 계정·콘텐츠 운영 처분이 아니라 정회원 본인도 수행하는 프로필 미디어 참조 제거이므로 위 중요 액션의 사유·감사 기록 대상에서 제외한다. CMS에서는 현재 Super Admin 역할을 다시 확인한다.
실패 처리¶
- 권한 정보 누락, 미정의 기능, 배정·소유 관계 불일치, 직접 URL/API 우회는 기본 허용하지 않는다.
- 권한 실패는 API 에러 계약 정책의
ErrorData로 반환하고, 민감정보를 제외한actor, 기능군, 대상 종류, 실패 범위와request_id를 구조화 로그에 남긴다. - 역할·연결 실패와 직접 대상 요청의 권한 실패를 빈 목록, 숨김 버튼, 성공 envelope 또는 조용한 return으로 바꾸지 않는다. 유효한 범위 조회 결과가 0건인 경우는 권한 실패가 아니다.
Mobile 캡처/녹화 보호¶
| Platform | Screenshot | Recording | User screen | Build | QA |
|---|---|---|---|---|---|
| Android | FLAG_SECURE |
FLAG_SECURE |
차단 |
release-only |
실기기 |
| iOS | secureTextEntry-layer, white |
isCaptured, white-overlay |
white |
release-only |
실기기 |
운영 절차¶
- 요청: 역할, 기능군, 행위, 데이터 범위, 사유와 영향 제품면을 기록한다.
- 정책 검토: 이 문서의 최대 범위와 도메인 정책의 세부 조건을 함께 갱신한다.
- 서버 적용: API의 허용·거부와 범위 검증을 먼저 또는 같은 배포 단위에서 반영한다.
- Admin 적용: 메뉴·route·버튼 표시를 서버 계약에 맞추고 클라이언트 단독 판단을 두지 않는다.
- 검증: Super Admin 허용, 일반 클럽매니저 허용 범위, 다른 배정·소유 데이터 거부, 직접 URL/API 거부를 각각 검증한다.
- 롤백: 권한 확대나 데이터 노출이 확인되면 서버에서 해당 operation을 우선 차단하고 직전 검증 기준점으로 복구한다.
증빙/추적¶
- PR/작업 보고에 권한 매트릭스 변경 전/후, 영향 operation과 Admin route, 허용·거부 테스트, 문서 동기화 결과를 남긴다.
- 권한 변경 배포는 감사 로그 조회 경로와 롤백 기준점을 릴리스 기록에 남긴다.
- 현행 구현과 이 정책의 불일치는 기술 부채 정리의
관리자 권한 서버 인가·표시 계약 미정렬에서 추적한다.
체크리스트¶
- [ ] 역할, 기능군, 행위, 데이터 범위를 독립적으로 판정하는가?
- [ ] 도메인 정책이 이 문서의 최대 범위를 넓히지 않고 더 좁히기만 하는가?
- [ ] 모든 Admin route와 API operation이 권한 매트릭스에 매핑됐는가?
- [ ] 직접 URL과 직접 API 요청이 UI와 같은 결론으로 거부되는가?
- [ ]
ASSIGNED·OWNED상세/변경 요청에서 대상 관계를 다시 검증하는가? - [ ] Super Admin·일반 클럽매니저·다른 담당/소유자·미정의 역할 테스트가 있는가?
- [ ] 권한 변경 감사 이력과 롤백 기준점이 있는가?
- [ ] 문서 거버넌스 정책의
정책 Composition Gate를 통과했는가?