# 07. 권한 ## 핵심 권한 검사는 두 층이다. **"이 종류의 작업을 해도 되나"**(권한 이름)는 유스케이스의 `@RequiresPermission` 선언과 web이 켜는 method security가 맡는다. **"이 객체를 봐도 되나"**(소유자·tenant)는 유스케이스가 객체를 읽은 뒤 직접 판정한다. ```text 요청 ─▶ 인증 필터(JWT 또는 세션) ─▶ AuthenticatedPrincipal(roles, tenant) ─▶ 컨트롤러 ─▶ [프록시] RequiresPermissionAuthorizationManager │ role → permission (app.authz.role-permissions) │ 없으면 403, 인증 없으면 401 ─▶ 유스케이스 본문 ─▶ 객체 로드 ─▶ 소유자·tenant 판정 ─▶ 남의 것이면 404(존재 숨김) ``` ## 작업 단위 권한: `@RequiresPermission` | 무엇 | 어디 | | --- | --- | | 선언 | `src/application-core/src/main/java/dev/caskeleton/application/security/RequiresPermission.java` — 쓰기 유스케이스에 필수(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`) | | 검사 장치 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/authz/MethodSecurityConfig.java`의 advisor | | 켜는 곳 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java` | | 역할 → 권한 | `app.authz.role-permissions` (`src/app-bootstrap/src/main/resources/config/security.yml`), 바인딩 `RolePermissionPolicy` | | 프록시 가능 | `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java` | 검사 자동 설정은 인증 체인(`WebSecurityAutoConfiguration`)과 **분리**되어 있다. 서비스가 자기 인증 방식으로 인증 체인을 바꿔도 권한 검사는 꺼지지 않는다(1라운드 07-03 수정). ### 지켜야 할 것 셋 1. 유스케이스는 **bean**이다. 직접 `new` 하면 프록시가 없어 선언이 주석이 된다. 2. 유스케이스 클래스와 그 public 메서드는 **final이 아니다**. final이면 프록시를 못 만들어 기동이 실패한다. 3. 유스케이스 안에서 자기 다른 메서드를 부르면(self-invocation) 프록시를 거치지 않는다. 권한이 다른 두 작업은 유스케이스 둘로 나눈다. ### 판단: 권한 이름과 역할 매핑 - **고르는 기준**: 운영자가 따로 주고 뺄 필요가 있는 작업인가. - **기본값**: `:`, resource는 kebab-case(`purchase-order:create`). 생성 명령은 `:create` 하나를 만든다. 역할 매핑은 권한을 명시적으로 나열한다(와일드카드 없음). - **예외**: 같은 역할이 항상 함께 가지는 작업은 한 역할에 여러 권한을 준다 (`operation-submit: operation:submit,operation:cancel`). - 매핑하지 않은 권한은 아무도 갖지 않는다. 새 기능의 쓰기는 매핑 전까지 모두 403이다 — 실수로 열리지 않는 쪽. - 읽기 유스케이스는 선언이 필수가 아니다. 인증된 누구나 읽으면 안 되는 데이터면 선언하거나 객체 판정을 둔다. ### 역할은 어디서 오나 JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `resource_access..roles`만 읽는다. audience는 필수다(1라운드 02-03 수정). 같은 issuer의 다른 client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지 않는다(`JwtToAuthenticatedPrincipalConverter`, `docs/runbooks/auth-audience-mismatch.md`). ## 객체 단위 권한 - **고르는 기준**: 같은 권한을 가진 두 사람이 같은 객체에 대해 다른 답을 받아야 하는가(소유자, tenant). - **기본값**: 유스케이스가 객체를 읽은 뒤 판정하고, 남의 것이면 **없는 것과 같은 404**로 답한다. 존재 여부도 정보다. 예: `GetDurableOperationUseCase`와 `DurableOperationAccessPolicy` (`src/application-core/src/main/java/dev/caskeleton/application/operation/`). - **예외**: 여러 전송이 같은 판정을 써야 하거나 목록에서 한 번에 판정해야 하면 `ObjectAccessPolicy`(`src/application-core/src/main/java/dev/caskeleton/application/security/ObjectAccessPolicy.java`, batch 메서드로 N+1 회피)를 구현한다. 존재를 숨길 필요가 없는 관리 화면은 403도 된다. - tenant: 인증 정보에서만 만든 `TenantId`를 command에 싣는다. 요청 본문의 tenant 값을 믿지 않는다. ## 시스템이 부르는 쓰기: `@SystemInvoked` 스케줄러·relay처럼 사람이 아니라 시스템이 부르는 쓰기 유스케이스는 `@RequiresPermission` 대신 `@SystemInvoked(reason = "...")`를 단다(`src/application-core/src/main/java/dev/caskeleton/application/security/SystemInvoked.java`). 스케줄러 스레드에는 인증이 없어 권한 선언은 장식이 되기 때문이다. 이 표시가 붙은 유스케이스는 **권한 검사가 없는 쓰기**이므로 전송 계층이 닿으면 안 된다. 그래서 두 가지가 막는다. | 막는 것 | 어디 | | --- | --- | | bean으로 등록하면 기동 실패. 조립 모듈이 `new`로 만들어 스케줄러에만 준다(예: `composition:outbox-relay`) | `src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java` | | inbound adapter가 그 클래스를 직접 쓰면 빌드 실패 | `INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) | D4 실패(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)를 끄려고 이 표시를 쓰지 않는다. 사용자가 부르는 쓰기라면 권한을 선언하고 역할에 매핑한다. ## web 없는 조립 web이 빠진 조립(gRPC 전용·배치 전용)에는 `@RequiresPermission`을 검사할 advisor가 없다. 그런 조립에 권한을 선언한 bean이 있으면 `PermissionEnforcementGuard`가 기동을 실패시킨다(리뷰 01-06). web 없이 조립하는 서비스는 자기 전송에 맞는 검사 advisor를 함께 넣어야 기동한다. ## 지금 이해하면 되는 것 - 쓰기 = `@RequiresPermission` + non-final + bean + 역할 매핑. - 시스템만 부르는 쓰기 = `@SystemInvoked` + bean 아님 + 전송에서 안 닿음. - 객체 판정은 유스케이스 안, 남의 것은 404. - 역할은 자기 client 것만 읽는다.