[Knowledge/RAG] private KB 배포 preflight 및 user_knowledge_permissions 구현

[HyungminYoon1]

배경

현재 Workflow LLM node RAG runtime은 보안상 올바르게 동작한다. execution_subject가 없으면 workflow owner, deployment owner, builder, user_id로 private KB 권한을 조용히 fallback하지 않고 anonymous public-only retrieval로 낮춘다.

하지만 배포 시점에는 사용자가 이 제약을 명확히 알기 어렵다. private Knowledge Base가 연결된 workflow를 공개 챗봇, webhook, schedule, API secret 등 non-interactive 방식으로 배포하면 실행 시 private KB를 읽지 못해 safe no-result 또는 근거 부족 응답이 발생할 수 있다.

또한 Knowledge Base content permission은 현재 team permission 중심이며, user_knowledge_permissions가 아직 없어 시스템 완성도와 Organization/RBAC 문서 목표 사이에 gap이 있다. 기존 관련 이슈 MBA-57과 연결해 이 이슈에서 user direct KB permission까지 함께 정리한다.

목표

1. 배포 전 private KB 사용 가능 여부를 preflight로 검사한다.
2. non-interactive 실행에서 private KB가 필요한 workflow는 배포 전에 safe warning/block을 반환한다.
3. public collection에 연결된 KB는 anonymous public-only 후보로 허용한다.
4. source-managed KB는 source/connector public exposure approval primitive가 구현되기 전까지 public-only 후보에서 fail-closed로 표시한다.
5. user_knowledge_permissions model/migration/API/helper를 추가해 user direct KB permission을 지원한다.
6. 문서와 테스트를 실제 구현에 맞게 갱신한다.

구현 범위

Deployment preflight

• Workflow graph의 LLM node knowledgeBases 참조를 검사한다.
• 각 KB가 active organization scope 안에 있는지 확인한다.
• KB가 public runtime에서 사용할 수 있는지 판정한다.
  • active public Knowledge Collection에 link된 active KB는 허용한다.
  • private KB는 non-interactive public/webhook/schedule/API secret 실행에서 block 또는 warning 처리한다.
  • source-managed KB는 현재 public exposure approval store가 없으므로 fail-closed로 처리한다.
• deployment create/toggle 또는 별도 preflight endpoint에서 safe result를 반환한다.
• UI는 배포 전에 "이 배포 방식에서는 private KB를 읽을 수 없음"을 명확히 표시한다.
• response/audit/log에는 hidden KB name, raw source path/url/title, exact denied count를 노출하지 않는다.

user_knowledge_permissions

• user_knowledge_permissions table/model/migration을 추가한다.
• user direct KB permission은 existing team KB permission과 같은 auth_state semantics를 따른다.
• get_effective_knowledge_base_auth_state와 has_knowledge_base_permission이 team + user direct permission을 합산한다.
• organization member removal cleanup에 user KB permission revoke를 포함한다.
• Admin/permission API 또는 Knowledge permission surface에서 user direct grant/revoke를 지원한다.
• source-managed KB에서는 user direct grant가 source ACL freshness/requester authorization gate를 우회하지 못한다.

Acceptance Criteria

• private KB가 연결된 workflow를 public/non-interactive deployment로 만들 때 preflight가 safe block/warning을 반환한다.
• public collection에 연결된 non-source-managed KB는 anonymous public-only runtime 후보로 유지된다.
• source-managed KB는 public exposure approval store가 없으면 public-only 후보에서 제외된다.
• workflow owner/builder/user_id fallback으로 private KB 접근이 생기지 않는 테스트가 유지된다.
• user direct KB permission row가 있으면 해당 user는 KB use/manage 권한을 받을 수 있다.
• user direct KB permission이 없고 team permission도 없으면 KB owner/user_id만으로 권한이 생기지 않는다.
• organization member removal 시 해당 user의 KB direct permission이 cleanup된다.
• 관련 문서가 실제 API/권한/runtime 동작과 일치하도록 갱신된다.

참고 문서

• local/system-completion-audit/knowledge-domain-gap-analysis-2026-07-09.md
• docs/features/knowledge/requirements.md
• docs/features/knowledge/api_spec.md
• docs/features/knowledge/implementation_baseline.md
• docs/decisions/ADR-0017-knowledge-integration-provisional-implementation-baseline.md
• docs/decisions/ADR-0018-workflow-rag-anonymous-public-only-runtime.md
• docs/decisions/ADR-0020-knowledge-mcp-incremental-sync-boundary.md

Non-goals

• service account 또는 assigned operator 기반 private RAG runtime 구현
• source public exposure approval store 구현
• MCP/API source connector 구현
• Knowledge Skill registry/context loader 구현
• raw artifact/raw-compliance access 구현

[linear-code]

MBA-176