[Architecture/BE][LLM Credential] Workflow LLM node credential selection policy 및 ProviderExecutionCapability 구현

[HyungminYoon1]

배경

nodease/mbased#196은 LLM node가 사용할 Provider credential을 사용자가 직접 선택하고 workflow graph에 저장하는 방식을 제안했습니다. 이후 공식 아키텍처는 다음과 같이 변경되었습니다.

• Workflow/Agent Builder graph에는 generation model_id만 저장하고 credential ID 또는 원문을 저장하지 않습니다.
• LLM Credentials domain이 provider/model/credential 권한과 verified relation을 검증하고 ProviderExecutionCapability를 발급합니다.
• 여러 credential 후보가 있을 때 name/order 기반 fallback이나 승인되지 않은 default credential/preset을 사용하지 않습니다.
• execution subject, credential principal, billing principal과 audit actor를 서로 다른 개념으로 유지합니다.

현재 runtime에는 organization-scoped credential routing 기반이 있지만, 다중 credential 모호성, deployment credential policy와 capability 발급·폐기 경계가 아직 완결되지 않았습니다.

목표

Workflow LLM node가 특정 credential secret 또는 client-selected owner에 결합되지 않으면서도, 동일 model을 지원하는 여러 credential 중 어떤 credential을 사용할지 결정하는 서버 소유 정책을 확정하고 ProviderExecutionCapability 기반 provider 호출 경계를 구현합니다.

구현 범위

Credential selection policy

• Workflow graph는 model_id만 저장한다는 기존 계약을 유지합니다.
• 명시적 deployment credential policy가 필요한지 결정하고 저장 위치, version/snapshot binding, 관리 권한을 정의합니다.
• 승인된 policy가 없고 사용 가능한 credential 후보가 여러 개라면 임의 name/order fallback 없이 typed ambiguity 또는 configuration-required 상태로 fail-closed합니다.
• credential candidate는 canonical organization, active 상태, credential use, verified credential-model relation, provider/model 일치를 모두 통과해야 합니다.
• credential revoke, permission revision 변경, model relation 변경은 다음 invocation부터 반영합니다.

ProviderExecutionCapability

• LLM Credentials domain을 capability schema·발급·revision·revoke 검증의 authoritative owner로 구현합니다.
• capability는 organization/workflow/deployment version, node invocation, execution admission, provider attempt, provider/model/credential safe reference, server-derived credential principal, permission decision revision, purpose, egress/pricing revision, token·cost cap과 expiry에 binding합니다.
• main_generation과 memory_summary purpose를 분리하고 capability 재사용을 차단합니다.
• raw credential, encrypted config와 capability token/scope 원문을 API, graph, audit, trace에 노출하지 않습니다.

Runtime 및 운영

• Gateway preflight와 Workflow Engine provider admission이 동일한 selection/capability 계약을 사용하도록 합니다.
• stale capability, wrong deployment version, wrong node/run/attempt, expired capability는 provider SDK 호출 전에 차단합니다.
• provider call 시작 후 revoke된 ambiguous outcome은 자동 재호출하지 않고 usage reconciliation과 분리합니다.
• permission denial, ambiguity, unavailable relation을 구분하는 redaction-safe reason code와 audit/trace 계약을 추가합니다.

문서와 테스트

• docs/features/llm-credentials/, workflow, deployment, conversation-memory 관련 문서를 갱신합니다.
• 별도 architecture 결정이 필요하면 ADR을 추가합니다.
• 단위, Gateway/Worker integration, PostgreSQL 권한 변경, retry/revoke edge case 테스트를 추가합니다.

완료 기준

• Workflow graph에 credential ID 또는 credential 원문이 저장되지 않습니다.
• 여러 credential 후보의 선택 또는 모호성 처리 정책이 문서와 코드에서 일치합니다.
• 임의 name/order fallback 없이 configuration-required 또는 승인된 deployment policy로만 결정됩니다.
• capability의 scope/revision/purpose/expiry가 일치할 때만 provider 호출이 허용됩니다.
• credential revoke와 permission/model relation 변경 뒤 stale capability로 새 호출을 할 수 없습니다.
• main/summary capability 교차 사용과 다른 run/node/attempt 재사용이 차단됩니다.
• raw secret과 capability 원문이 API, graph, audit, trace, fixture에 노출되지 않습니다.

비범위

• credential secret at-rest encryption/rotation
• 중앙 외부 LLM Gateway 제품 도입
• 개인 사용자 전용 credential
• model routing 및 Cost Optimizer 정책 재설계

관련

• [Feat] LLM 노드 Provider 선택 기능 추가 #196: 기존 client-side Provider credential 선택 제안
• [BE][Infra] Organization-level LLM credential routing과 runtime use 권한 적용 #58: organization-level credential routing 및 runtime use 기반
• [Architecture][Memory] Conversation Memory 계약 공백 보강 #352: ProviderExecutionCapability authoritative owner 계약

2026-07-16 Public execution principal·usage 검토 반영

최신 origin/dev @ 977d37f0에서는 anonymous/public deployment 실행이 app.created_by를 legacy user_id로 합성하고, LLM runtime이 명시적 credential_principal 부재 시 이를 fallback으로 사용할 수 있다. Usage 기록도 WorkflowRun projection 생성 순서에 의존해 누락될 수 있다.

• ProviderExecutionCapability 적용 시 execution subject, credential principal, billing principal, audit actor를 별도 typed context로 강제한다.
• 공개 실행에서 App creator를 credential principal/actor로 자동 대체하지 않는다.
• nodease/mbased#475을 하위 이슈로 두고 provider usage durable ledger와 WorkflowRun projection/reconciliation을 구현한다.
• 이 선행 계약이 완료되기 전 nodease/mbased#398의 target Memory runtime을 시작하지 않는다.

활성화 전 후속 게이트 (2026-07-20 정합성 보정)

이 이슈는 ProviderExecutionCapability foundation을 dormant 상태로 병합할 수 있으나, 다음 소비 경계가 완료되기 전 target Memory/RAG production activation 근거로 사용하지 않는다.

• nodease/mbased#581가 container_path + node_id canonical identity를 구현하기 전에는 nested Loop/subGraph의 LLM node를 capability 대상에서 fail-closed한다.
• nodease/mbased#580이 query embedding capability를 구현하기 전에는 Knowledge-enabled RAG가 provider embedding 호출을 시작하지 않는다.
• nodease/mbased#475의 durable provider usage ledger와 principal 분리가 완료되어야 provider 시작·unknown outcome·reconciliation이 추적 가능하다.
• nodease/mbased#290의 승인된 outbound HTTPS/egress 정책을 실제 provider adapter가 통과해야 한다. routing fingerprint나 catalog revision은 egress authorization을 대체하지 않는다.
• ADR 번호와 migration parent는 작업 브랜치 생성 시점 값으로 고정하지 않고 최신 origin/dev rebase 뒤 다시 산정한다.

preflight와 runtime은 위 미완료 capability를 성공으로 추정하지 않고 typed configuration/capability error로 차단하며 provider 외부 I/O를 수행하지 않는다.

[linear-code]

MBA-249