검증 가능한 의도 (커머스 게이팅)

검증 가능한 의도(Verifiable Intent, VI)는 커머스 게이팅 에이전트 액션 — 결제, 장바구니 체크아웃, 또는 사용자의 명시적이고 범위가 지정된 동의가 필요한 고위험 트랜잭션 — 을 위한 Revka의 암호화 기반 인가 레이어입니다. 에이전트가 “당연히” 한도 내에서만 지출할 것이라는 신뢰에 의존하는 대신, VI는 서명된 SD-JWT 자격 증명 체인을 바인딩하여 검증자가 최종 값이 사용자 설정 한도 내에서 사용자로부터 인가받았음을 증명할 수 있도록 합니다.

결제 또는 체크아웃 플로우에 Revka를 통합하면서 에이전트가 사용자를 대신해 행동하되 무제한 지출 권한은 부여하고 싶지 않을 때 이 페이지를 참고하세요. VI는 커머스 툴 호출을 게이팅하는 내부 서브시스템으로, Approval Manager, OTP 게이팅, 보안 모델 전체를 대체하는 것이 아니라 이들을 보완합니다.

참고

Revka의 VI 구현은 Verifiable Intent 오픈 사양(agent-intent, Apache 2.0)을 Rust로 새롭게 구현한 것입니다. 해당 사양의 SD-JWT 계층형 자격 증명 설계, 제약 모델, 3계층 체인을 따르지만, 레퍼런스 구현의 소스 코드를 복사하지는 않습니다.

계층형 자격 증명 체인

VI는 인가를 서명된 자격 증명의 체인으로 모델링하며, 각 계층은 해시를 통해 상위 계층에 바인딩됩니다. 검증자는 체인을 위에서 아래로 순회하며, 바인딩, 서명, 타임스탬프, 제약 조건 검사 중 하나라도 실패하면 트랜잭션을 거부합니다.

계층	서명자	포함 내용
L1	자격 증명 제공자 → 사용자	결제 수단 SD-JWT(pan_last_four, scheme, cnf를 통한 카드 바인딩). 외부에서 발급되며 Revka의 범위 밖입니다.
L2	사용자 → 에이전트 / 검증자	의도를 위임하는 KB-SD-JWT. Immediate(최종 값 확정) 또는 Autonomous(제약 조건 기반) 방식입니다.
L3a	에이전트 → 결제 네트워크	에이전트가 서명한 최종 결제 값(payment_instrument, payment_amount, payee, transaction_id). Autonomous 모드 전용.
L3b	에이전트 → 판매자	에이전트가 서명한 최종 체크아웃 값(checkout_jwt, checkout_hash, 확정된 line_items). Autonomous 모드 전용.

각 바인딩은 B64U(SHA-256(ASCII(parent)))로 계산됩니다.

• L2의 sd_hash는 직렬화된 L1의 해시와 일치해야 합니다.
• L3b의 checkout_hash는 해당 checkout_jwt의 해시와 일치해야 합니다.
• L3a의 transaction_id는 L3b의 checkout_hash와 일치해야 합니다(교차 참조: 결제를 특정 체크아웃에 연결).

모든 금액은 ISO 4217에 따라 **정수 소수 단위(센트)**로 표현됩니다 — 27999는 $279.99를 의미합니다. 이를 통해 체인 전반에 걸친 부동소수점 및 소수 표현의 모호성을 제거합니다. 서명에는 ECDSA P-256(ES256)을 사용하며, 해시는 SHA-256으로 계산하고 패딩 없이 base64url 인코딩합니다.

Immediate vs Autonomous 위임

L2 위임 모드는 에이전트에게 부여되는 재량의 범위를 결정하며, VI 플로우를 설계할 때 핵심적인 의사결정 사항입니다.

Immediate (2계층) 사용자가 정확한 최종 값을 확인합니다. 에이전트 위임이 없으며, 에이전트는 사용자가 이미 승인한 값을 단순히 전달합니다. L2에는 FinalCheckoutMandate와 FinalPaymentMandate가 포함됩니다. L3 계층과 제약 조건이 없습니다.

Autonomous (3계층) 사용자가 제약 조건을 설정하고 에이전트의 키(cnf)를 바인딩합니다. 에이전트는 그 범위 내에서 최종 값을 직접 결정하고 L3a/L3b에 서명합니다. L2에는 OpenCheckoutMandate와 OpenPaymentMandate가 포함됩니다.

모드는 위임의 vct(검증 가능한 자격 증명 유형)로부터 추론됩니다.

vct	모드
mandate.checkout, mandate.payment	Immediate
mandate.checkout.open, mandate.payment.open	Autonomous

위임 쌍은 항상 필수입니다 — 체크아웃 위임 및 결제 위임이 모두 있어야 합니다. 쌍이 불완전하면 검증에 실패합니다(IncompleteMandatePair). Immediate 모드에서는 L2에 cnf 에이전트 키 바인딩이 없어야 하며, Autonomous 모드에서는 반드시 있어야 합니다(그렇지 않으면 ModeMismatch가 발생합니다).

주의

Immediate 모드가 더 안전한 기본값입니다. 사용자가 정확한 금액과 수신자를 직접 승인하므로 에이전트에게는 지출 재량이 전혀 없습니다. Autonomous 모드는 에이전트가 최종 값을 직접 결정해야 할 때(예: 항목 선택 또는 동의 시점에 알 수 없는 가격 확정)만 사용하며, 이 경우에도 제약 조건을 엄격하게 설정하세요.

제약 조건 유형

제약 조건은 L2 Autonomous 위임에 포함되며, 에이전트가 수행할 수 있는 행동의 범위를 제한합니다. 검증 시에는 이행(fulfillment) 객체 — 에이전트가 실제로 제안하는 내용(판매자, 수취인, 금액, 통화, 항목)에 대한 검증자의 뷰 — 를 기준으로 평가됩니다. 제약 조건의 type 문자열은 VI 사양과 정확히 일치합니다.

제약 조건	type	제한 범위
허용 판매자	mandate.checkout.allowed_merchant	체크아웃 판매자가 allowed_merchants의 항목 중 하나와 일치해야 합니다.
항목 목록	mandate.checkout.line_items	장바구니의 각 항목이 어떤 항목의 acceptable_items에 포함되어야 합니다(빈 acceptable_items = 와일드카드). 총 수량이 항목별 quantity 값의 합을 초과해서는 안 됩니다.
허용 수취인	payment.allowed_payee	결제 수취인이 allowed_payees의 항목 중 하나와 일치해야 합니다.
결제 금액	payment.amount	트랜잭션당 범위. 선택적 min / max(센트)와 currency. 통화는 이행과 일치해야 합니다.
결제 예산	payment.budget	누적 한도(max, 센트). 에이전트 레벨에서는 단일 트랜잭션 ≤ 한도를 확인하며, 트랜잭션 간 누적 추적은 결제 네트워크의 책임입니다.
결제 반복	payment.recurrence	판매자 관리 반복 결제(frequency, start_date, 선택적 end_date / number). 에이전트 레벨에서는 통과 처리되며, 결제 네트워크에서 적용합니다.
에이전트 반복	payment.agent_recurrence	에이전트 관리 반복 구매(frequency, start_date, 선택적 end_date / max_occurrences). 에이전트 레벨에서는 통과 처리됩니다.
결제 참조	payment.reference	결제 위임을 체크아웃 위임에 연결하는 교차 참조 바인딩(conditional_transaction_id). 이행이 아닌 구조적으로 검증됩니다.

엔티티 매칭(판매자 및 수취인)은 사양 우선순위를 따릅니다. 양측 모두 id가 있으면 id로 매칭하고, 그렇지 않으면 (name, website) 쌍으로 매칭합니다.

알아두어야 할 몇 가지 평가 규칙:

• 빈 허용 목록(판매자, 수취인, 또는 항목 목록)은 충족 불가로 처리되어 항상 위반으로 간주됩니다. 모든 것을 허용하는 것으로 묵시적으로 처리되지 않습니다.
• 이행에 판매자 또는 수취인 정보가 없으면 해당 허용 목록 검사는 건너뜁니다(사양에 따라 검증 불가). 단, 금액이 없으면 payment.amount와 payment.budget 검사가 실패합니다.
• 각 위반은 기계가 읽을 수 있는 종류(AmountOutOfRange, BudgetExceeded, CurrencyMismatch, MerchantNotAllowed, PayeeNotAllowed, LineItemViolation 등)를 포함하므로, 정책 엔진이 텍스트를 파싱하지 않고도 위반 원인에 따라 분기할 수 있습니다.

제약 조건 세트 예시

[
  {
    "type": "mandate.checkout.allowed_merchant",
    "allowed_merchants": [
      { "name": "Example Store", "website": "https://store.example.com" }
    ]
  },
  {
    "type": "payment.amount",
    "currency": "USD",
    "min": 10000,
    "max": 40000
  },
  {
    "type": "payment.budget",
    "currency": "USD",
    "max": 50000
  }
]

이 설정은 에이전트가 특정 판매자에서 트랜잭션당 $100.00~$400.00 범위 내에서, 최대 $500.00까지 체크아웃하도록 인가합니다.

vi_verify 툴

VI는 vi_verify 툴을 통해 에이전트 루프에 노출됩니다. 이는 읽기 클래스 작업(보안 정책에서 Read로 게이팅)으로, operation 인수를 통해 세 가지 작업을 제공합니다.

operation	목적	필수 인수
verify_binding	두 자격 증명 계층 간의 sd_hash 바인딩을 확인합니다.	sd_hash, serialized_parent
verify_timestamps	300초 클럭 스큐 허용 범위로 iat / exp를 검증합니다.	iat, exp
evaluate_constraints	이행 데이터를 기준으로 제약 조건 배열을 검증합니다.	constraints, fulfillment

제약 조건 평가

{
  "operation": "evaluate_constraints",
  "constraints": [
    { "type": "payment.amount", "currency": "USD", "min": 10000, "max": 40000 }
  ],
  "fulfillment": { "amount": 27999, "currency": "USD" }
}

응답(툴의 output은 JSON 문자열입니다):

{
  "all_satisfied": true,
  "results": [
    { "constraint_type": "payment.amount", "satisfied": true, "violations": [] }
  ]
}

제약 조건이 위반되면 all_satisfied는 false가 되고, 위반 항목에 violations가 나열되며, 툴은 one or more constraints violated 오류와 함께 실패를 보고합니다.

해시 바인딩 검증

{
  "operation": "verify_binding",
  "sd_hash": "<expected B64U(SHA-256(parent))>",
  "serialized_parent": "<serialized parent SD-JWT>"
}

일치하면 sd_hash binding verified를 반환하고, 불일치하면 VI/SdHashMismatch 오류를 반환합니다.

[verifiable_intent] 설정

VI 검증은 기본적으로 비활성화되어 있습니다. ~/.revka/config.toml에서 활성화하세요.

[verifiable_intent]
enabled = false        # turn on VI credential verification for commerce tool calls
strictness = "strict"  # "strict" | "permissive"

키	타입	기본값	의미
enabled	bool	false	커머스 툴 호출에 대한 VI 자격 증명 검증을 활성화합니다.
strictness	string	"strict"	제약 조건 평가 엄격도 모드(아래 참조).

strictness 설정은 체인 검증 중 알 수 없는 제약 조건 유형의 처리 방식을 제어합니다.

• strict — 인식할 수 없는 제약 조건 유형은 위반으로 처리됩니다(실패-폐쇄). 프로덕션 환경에 권장됩니다. 검증자가 이해하지 못하는 제약 조건은 묵시적으로 통과시켜서는 안 됩니다.
• permissive — 인식할 수 없는 제약 조건 유형은 경고와 함께 건너뜁니다(실패-개방). 현재 빌드보다 최신 위임의 제약 조건 유형과 상호 운용해야 할 때만 사용하세요.

주의

특별한 상호 운용성 이유가 없는 한 strictness = "strict"를 유지하세요. permissive 모드에서는 현재 빌드가 평가할 수 없는 제약 조건이 충족된 것으로 처리되어, 사용자가 제한하려 했던 트랜잭션이 통과될 수 있습니다.

설정 우선순위 및 config.toml 조회 방식에 대한 자세한 내용은 설정 개요를 참조하세요.

체인에서의 검증 흐름

VI가 활성화된 상태에서 에이전트가 커머스 액션을 시도하면, 검증자는 체인을 순서대로 순회합니다. 개념적으로는 다음과 같습니다.

1. 타임스탬프 — 각 계층의 iat / exp를 ±300초 스큐 허용 범위로 확인합니다. 만료되었거나 아직 유효하지 않은 자격 증명은 거부됩니다(Expired / NotYetValid).

2. 바인딩 — L2의 sd_hash를 L1과 대조하여 확인합니다. Autonomous 모드에서는 L3b의 checkout_hash를 해당 checkout_jwt와 대조하고, L3a의 transaction_id를 L3b의 checkout_hash와 교차 참조합니다.

3. 모드 — 위임의 vct 값으로 모드(Immediate vs Autonomous)를 결정하고, 해당 모드에 맞게 에이전트 키 cnf의 존재 여부를 검증합니다.

4. 제약 조건 — Autonomous 모드에서는 에이전트가 제안하는 이행을 기준으로 모든 L2 제약 조건을 평가합니다. 충족되지 않은 제약 조건이 있으면 트랜잭션이 차단됩니다.

모든 검사를 통과한 경우에만 게이팅된 커머스 툴이 진행됩니다. 각 오류에 기계가 읽을 수 있는 종류가 있으므로, 주변 정책 로직이 차단, 재시도, 또는 에스컬레이션 여부를 결정할 수 있습니다.

관련 페이지

보안 모델 VI가 Revka의 심층 방어 레이어에서 어떻게 작동하는지 설명합니다.

자율성 및 승인 VI 아래에 위치하는 자율성 수준과 툴 호출 승인 게이트.

OTP 게이팅 및 긴급 정지 고위험 액션에 일회용 비밀번호 챌린지 또는 킬 스위치를 추가합니다.

정책, 명령 및 샌드박싱 명령 허용 목록, 위험 분류, Approval Manager.