Knowledge Base RBAC enforcement 및 user direct permission 분리 구현

[hojun-lee99]

작업 설명

nodease/mbased#15에서 분리된 Knowledge Base RBAC 후속 작업이다. nodease/mbased#15는 Organization/Team 관리 API와 workflow/LLM permission grant/revoke, 그리고 MVP1 공용 enforcement 기반까지만 다룬다.

이 이슈는 최신 docs/ 기준으로 Knowledge/RAG API의 organization scope, KB permission matrix, user direct knowledge permission, RAG runtime use enforcement를 정렬한다.

문서 기준

Source of truth:

• docs/data-model/rbac-permission-policy.md
• docs/data-model/physical-data-model.md
• docs/api/knowledge-rag.md
• docs/architecture/knowledge-rag.md
• docs/architecture/auth-rbac.md

특히 최신 문서 기준에서 반드시 반영할 점:

• Knowledge/RAG org-scoped API는 목표 계약상 X-Organization-Id active organization context를 사용한다.
• Header가 없으면 400 organization.required, header organization이 KB organization_id와 다르거나 요청 user scope 밖이면 404 resource.not_found로 숨긴다.
• Active organization_memberships row는 KB organization scope와 permission subject의 prerequisite이다.
• Invited/suspended/removed membership은 fail-closed 처리한다.
• Active organization membership만으로 KB read/use를 허용하지 않는다.
• 실제 KB 허용은 organization manager override, team_knowledge_permissions, user_knowledge_permissions의 effective permission으로 판정한다.
• Metadata는 permission source of truth가 아니다.

상세 작업

Data Model / Schema

• user_knowledge_permissions 모델과 migration을 추가한다.
• user_knowledge_permissions는 additive allow 전용으로 구현한다. team 권한을 낮추거나 deny하지 않는다.
• (grantee_organization_id, user_id, knowledge_base_id) unique 기준을 둔다.
• grantee_organization_id와 user_id는 active organization_memberships prerequisite을 만족해야 한다.
• team_knowledge_permissions와 user_knowledge_permissions의 effective auth_state 계산을 공용 RBAC service/helper에 연결한다.
• 허용되지 않은 auth_state 값은 none과 동일하게 fail-closed 처리한다.

Organization Scope / API Contract

• Knowledge/RAG org-scoped endpoint에서 X-Organization-Id active context를 평가한다.
• Header 누락은 400 organization.required로 처리한다.
• 요청 organization이 user scope 밖이거나 KB/document organization과 불일치하면 404 resource.not_found로 숨긴다.
• 같은 organization scope 안에서 필요한 KB permission이 부족하면 403 permission.denied로 처리한다.
• 기존 primary organization fallback은 과도기 호환 경로로만 남기고, 새 enforcement는 header 기반 목표 계약으로 수렴한다.

Enforcement

• Knowledge base read 권한을 Gateway KB 목록/상세/document metadata 조회에 적용한다.
• Knowledge base write 권한을 문서 업로드/삭제/재색인/설정 수정에 적용한다.
• Knowledge base use 권한을 RAG search-test chat/pure에 적용한다.
• Knowledge base use 권한을 Workflow Engine RAG node 실행 직전에 적용한다.
• 기존 KB upload, document analyze, confirm, progress 등 현재 owner/scope 검증이 약한 RAG endpoint를 KB organization scope와 permission 기준으로 정렬한다.
• Knowledge base manage 권한을 향후 KB permission grant/revoke API의 권한 기준으로 사용한다.
• connection use는 connection permission table이 아니라 consuming knowledge base 권한으로 허용한다.
• document별 permission table은 만들지 않고, document access/policy는 KB permission과 documents.meta_info 기반 metadata policy로 조합한다.

Audit / Policy Event

• Team knowledge permission grant/revoke audit는 기존 표준 action을 유지한다.
  • team_knowledge_permission.created
  • team_knowledge_permission.updated
  • team_knowledge_permission.deleted
• User knowledge permission grant/revoke audit를 표준 action으로 기록한다.
  • user_knowledge_permission.created
  • user_knowledge_permission.updated
  • user_knowledge_permission.deleted
• Knowledge permission denied audit에 resource_type, resource_id, required_action, effective_auth_state, organization_id를 포함한다.
• KB/RAG RBAC 거부 action은 permission.denied를 사용한다.
• 성공한 retrieval audit는 rag.retrieve를 사용한다.
• Metadata policy 경고/차단이 이 이슈 범위에 포함되는 경우 policy.warn, policy.block action과 audit_metadata.policy_result를 사용한다. Metadata-aware/hierarchical RAG 본작업과 겹치는 항목은 nodease/mbased#122로 분리한다.

테스트 기준

• active organization membership이 없으면 KB permission row가 있어도 deny된다.
• invited/suspended/removed membership은 fail-closed로 deny된다.
• team knowledge permission이 없으면 deny by default로 처리된다.
• auth_state='none'이면 deny된다.
• invalid auth_state는 fail-closed로 deny된다.
• viewer는 read만 가능하다.
• operator는 read/use 가능, write/manage 불가다.
• builder는 read/write/use 가능, manage 불가다.
• manager는 read/write/use/manage 가능하다.
• user direct permission은 team permission과 합산되어 더 높은 auth_state가 effective permission이 된다.
• 낮은 user direct permission이 높은 team permission을 낮추지 않는다.
• inactive team의 permission row는 effective permission 계산에서 제외된다.
• X-Organization-Id 누락은 400 organization.required로 처리된다.
• 요청 organization scope 밖이거나 KB organization 불일치는 404 resource.not_found로 숨긴다.
• 같은 scope 안에서 권한 부족은 403 permission.denied로 처리된다.
• RAG search-test 실행 시 knowledge base use 권한이 없으면 차단된다.
• RAG node 실행 시 knowledge base use 권한이 없으면 provider/retrieval 호출 전 차단된다.
• 기존 KB upload/analyze/confirm/progress 경로가 KB scope와 permission을 우회하지 못한다.
• grant/revoke/denied/retrieval audit 기록을 검증한다.

제외 항목

• connection 전용 permission table은 만들지 않는다.
• document별 permission table은 만들지 않는다.
• roles, user_roles, polymorphic resource_permissions는 만들지 않는다.
• rag_retrieval_traces 신규 table은 만들지 않는다.
• knowledge_bases.classification, documents.classification column은 만들지 않는다.
• Metadata-aware filter, hierarchical retrieval schema/flow, retrieval trace payload 전체 구현은 [BE][RAG] Metadata-aware 및 Hierarchical RAG 1단계 구현 #122 범위와 충돌하지 않게 분리한다.

분리 출처: #15

[linear-code]

MBA-57