Module: Portage::Ucp::PolicyGuard

Defined in:
lib/portage/ucp/policy_guard.rb

Overview

In-core policy gate (docs/plans/agentic-payments.md Phase 2) called from Dispatcher before any payment-completing dispatch, alongside the existing PaymentTokenGuard call. Guards agent mistakes (a runaway loop, a merchant typo, a misused token), not a compromised agent — anyone running as the local user can edit the policy file; the real backstop against that is an issuer-side limit, documented in the README, not this module.

Public API is kept deliberately small and stable since portage-ucp is a published gem — the Policy file format behind it is free to change across releases.

Class Method Summary collapse

Class Method Details

.check!(amount:, currency:, merchant:, token_ref:, policy: Portage::Ucp::Policy.load, transaction_log: Portage::Ucp::Support::TransactionLog.new) ⇒ Hash

Returns the passing decision, suitable for TransactionLog#record_decision / #complete's policy_decision:.

Parameters:

  • amount (Integer, nil) —

    minor-unit amount, from the checkout Dispatcher fetches before dispatch. nil skips the two cap checks (an adapter that can't price a checkout up front has nothing for a spend cap to compare against) but never skips velocity/allowlist/ scope — those don't need an amount to matter.

  • currency (String, nil)
  • merchant (String, nil) —

    the shop identity Dispatcher was built with (shop:) — one Dispatcher instance completes charges for one store, so this isn't a per-call argument the caller picks.

  • token_ref (String, nil) —

    from Support::TokenRef.for.

Returns:

  • (Hash) —

    the passing decision, suitable for TransactionLog#record_decision / #complete's policy_decision:.

Raises:



30
31
32
33
34
35
36
37
38
 
# File 'lib/portage/ucp/policy_guard.rb', line 30

def self.check!(amount:, currency:, merchant:, token_ref:, policy: Portage::Ucp::Policy.load,
                transaction_log: Portage::Ucp::Support::TransactionLog.new)
  check_spend_cap(amount, currency, merchant, policy, transaction_log)
  check_velocity(merchant, policy, transaction_log)
  check_merchant_allowlist(merchant, policy)
  check_token_scope(amount, currency, merchant, token_ref, policy)

  { allowed: true }
end