QWED UCP guards for AI commerce verification

Total = Subtotal - Discount + Tax + Shipping + Fee

driver = MoneyGuard()
result = driver.verify_cart_totals(
    line_items=[{"price": 35.00, "quantity": 2}, {"price": 15.00, "quantity": 1}],
    taxes=8.25,
    discounts=10.00,
    claimed_total=98.25
)
# Returns: {"verified": True}

incomplete → ready_for_complete → completed
                              ↓
                            failed
                              ↓
                           cancelled

from qwed_ucp.guards.state_guard import StateGuard

guard = StateGuard()
# Check if we can SHIP given the current state is PAID
result = guard.verify_transition(
    current_state="paid",
    action="ship"
)
# Returns: {"verified": True}

from qwed_ucp.guards import SchemaGuard

guard = SchemaGuard()
result = guard.verify(checkout_data)

from qwed_ucp.guards import LineItemsGuard

guard = LineItemsGuard()
result = guard.verify({
    "line_items": [
        {"id": "roses", "quantity": 2, "item": {"price": 35.00}},
        {"id": "pot", "quantity": 1, "item": {"price": 15.00}}
    ],
    "totals": [{"type": "subtotal", "amount": 85.00}]  # 2×35 + 1×15 = 85 ✓
})

from qwed_ucp.guards import DiscountGuard
from decimal import Decimal

guard = DiscountGuard()
result = guard.verify_percentage_discount(
    subtotal=Decimal("100.00"),
    discount_amount=Decimal("10.00"),
    percentage=Decimal("10")  # 10% of 100 = 10 ✓
)

result = guard.verify_fixed_discount(
    subtotal=Decimal("50.00"),
    discount_amount=Decimal("5.00")  # Fixed $5 off ✓
)

from qwed_ucp.guards import CurrencyGuard

guard = CurrencyGuard()
result = guard.verify({"currency": "USD"})

# Valid - no decimals
{"currency": "JPY", "totals": [{"type": "total", "amount": 1000}]}

# Invalid - JPY shouldn't have decimals
{"currency": "JPY", "totals": [{"type": "total", "amount": 1000.50}]}

from qwed_ucp.guards.refund import RefundGuard
from decimal import Decimal

guard = RefundGuard()
result = guard.verify_full_refund(
    original_total=Decimal("100.00"),
    refund_amount=Decimal("100.00")
)
# Returns: RefundGuardResult(verified=True, details={"refund_type": "full"})

result = guard.verify_partial_refund(
    original_total=Decimal("100.00"),
    refund_amount=Decimal("50.00"),
    percentage=Decimal("50")  # 50% of 100 = 50 ✓
)

result = guard.verify_tax_reversal(
    original_tax=Decimal("10.00"),
    refund_tax=Decimal("5.00"),
    refund_percentage=Decimal("50")  # 50% of tax reversed ✓
)

checkout = {"totals": [{"type": "total", "amount": 100.00}]}
refund = {"amount": 100.00, "type": "full"}
result = guard.verify(checkout, refund)

from qwed_ucp.guards.tip import TipGuard
from decimal import Decimal

guard = TipGuard()
result = guard.verify_percentage_tip(
    subtotal=Decimal("50.00"),
    tip_amount=Decimal("9.00"),
    percentage=Decimal("18")  # 18% of 50 = 9 ✓
)
# Returns: TipGuardResult(verified=True, details={"tip_type": "pre-tax"})

result = guard.verify_post_tax_tip(
    total=Decimal("108.00"),
    tip_amount=Decimal("21.60"),
    percentage=Decimal("20")  # 20% of 108 = 21.60 ✓
)
# Returns: TipGuardResult(verified=True, details={"tip_type": "post-tax"})

result = guard.verify_tip_bounds(
    tip_amount=Decimal("20.00"),
    base_amount=Decimal("100.00")
)

from qwed_ucp.guards.fee import FeeGuard
from decimal import Decimal

guard = FeeGuard()
result = guard.verify_service_fee(
    subtotal=Decimal("100.00"),
    fee_amount=Decimal("5.00"),
    percentage=Decimal("5")  # 5% of 100 = 5 ✓
)
# Returns: FeeGuardResult(verified=True, details={"fee_type": "service"})

# Formula: base_fee + (distance × rate_per_km)
result = guard.verify_delivery_fee(
    claimed_fee=Decimal("13.00"),
    distance_km=Decimal("5"),
    rate_per_km=Decimal("2.00"),
    base_fee=Decimal("3.00")  # 3 + 5×2 = 13 ✓
)
# Returns: FeeGuardResult(verified=True, details={"fee_type": "delivery"})

result = guard.verify_platform_fee(
    fee_amount=Decimal("15.00"),
    subtotal=Decimal("100.00"),
    max_percentage=Decimal("30")  # 15% < 30% max ✓
)

import uuid
from qwed_ucp import UCPVerifier
from qwed_ucp.guards.attestation import AttestationGuard

# Production: provide a secret key or set QWED_ATTESTATION_SECRET env var
guard = AttestationGuard(secret_key="your-secret-key")

# Dev mode: use allow_insecure=True (generates a random secret)
guard = AttestationGuard(allow_insecure=True)

# Bindings for this verification event
transaction_attempt_id = str(uuid.uuid4())
request_nonce = str(uuid.uuid4())

# You can pass a UCPVerificationResult directly — no need to convert to a dict
checkout = {"currency": "USD", "totals": [{"type": "total", "amount": 82.79}]}
verifier = UCPVerifier()
verification = verifier.verify_checkout(checkout)

signed = guard.sign_checkout(
    checkout=checkout,
    verification_result=verification,
    guards_passed=[g.guard_name for g in verification.guards if g.verified],
    transaction_attempt_id=transaction_attempt_id,
    request_nonce=request_nonce,
    session_id="sess_abc123",       # optional
    merchant_id="merchant_42",       # optional
)

print(signed.token)                              # JWT token string
print(signed.verified)                          # True on success
print(signed.details["attestation_id"])          # UUID — matches JWT `jti`
print(signed.details["checkout_hash"])           # SHA-256 of checkout

result = guard.verify_attestation(
    token="eyJ...",
    expected_transaction_attempt_id=transaction_attempt_id,
    expected_request_nonce=request_nonce,
    expected_session_id="sess_abc123",   # optional, enforced if provided
    expected_merchant_id="merchant_42",   # optional, enforced if provided
    consume=True,                         # mark token consumed to prevent replay
)

print(result.verified)  # True if valid, unexpired, bindings match, not consumed
print(result.details)   # Decoded JWT payload

receipt = guard.create_receipt(
    checkout=checkout,
    verification_result=verification,
    attestation_id=signed.details["attestation_id"],
    transaction_attempt_id=transaction_attempt_id,
    previous_receipt_id=None,   # optional predecessor for audit chains
)

print(receipt["receipt_id"])              # "QWED-<attestation-id-uppercase>"
print(receipt["attestation_id"])          # Matches the JWT `jti`
print(receipt["transaction_attempt_id"])  # Same value passed to sign_checkout
print(receipt["verified"])                # True
print(receipt["engine"])                  # "QWED-Deterministic-v1"

from qwed_ucp import UCPVerifier, TrustStatus

verifier = UCPVerifier()
result = verifier.verify_checkout(checkout_data)

if result.status == TrustStatus.VERIFIED:
    # Safe to proceed to payment
    ...
elif result.status == TrustStatus.FAILED:
    # A guard deterministically disproved the transaction
    return reject(reason="proof_failed", errors=result.errors)
elif result.status == TrustStatus.ENGINE_ERROR:
    # A guard raised an exception — fail closed and page an operator
    return reject(reason="verifier_unavailable")
else:
    # UNVERIFIABLE / UNSUPPORTED / PARTIAL — treat as untrusted
    return reject(reason=str(result.status))

from qwed_ucp import UCPVerifier, TrustStatus

verifier = UCPVerifier()
result = verifier.verify_checkout(checkout_data)

print(f"Verified: {result.verified}")
print(f"Status: {result.status}")                      # TrustStatus.VERIFIED
print(f"Engine: {result.engine}")                     # "QWED-Deterministic-v1"
print(f"Mode: {result.verification_mode}")             # "deterministic"
print(f"Guards passed: {len([g for g in result.guards if g.status == TrustStatus.VERIFIED])}")