opentrust-payment-contracts 1.0.0__tar.gz

opentrust_payment_contracts-1.0.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: opentrust-payment-contracts
+Version: 1.0.0
+Summary: Abstract payment contracts for OpenTrust payment providers
+Author-email: Novel Hut Studios <founder@novelhut.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Costder/opentrust
+Project-URL: Repository, https://github.com/Costder/opentrust
+Project-URL: Issues, https://github.com/Costder/opentrust/issues
+Keywords: opentrust,payments,escrow,ai-agents,tool-marketplace
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.7
+Requires-Dist: cryptography>=42
+
+# Payment Contracts
+
+This package defines the abstract payment interface for OpenTrust registries.
+
+Registry operators who want to enable paid tool access implement the `PaymentGateway`, `EscrowProvider`, and `SubscriptionManager` interfaces against the OpenTrust schema. The reference registry ships a mock checkout provider for demos and keeps production secrets out of source control.
+
+The schema driving these interfaces is in `passport-schema/commercial-status.schema.json` and `passport-schema/escrow.schema.json`.

opentrust_payment_contracts-1.0.0/README.md

@@ -0,0 +1,7 @@
+# Payment Contracts
+
+This package defines the abstract payment interface for OpenTrust registries.
+
+Registry operators who want to enable paid tool access implement the `PaymentGateway`, `EscrowProvider`, and `SubscriptionManager` interfaces against the OpenTrust schema. The reference registry ships a mock checkout provider for demos and keeps production secrets out of source control.
+
+The schema driving these interfaces is in `passport-schema/commercial-status.schema.json` and `passport-schema/escrow.schema.json`.

opentrust_payment_contracts-1.0.0/opentrust_payment_contracts.egg-info/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: opentrust-payment-contracts
+Version: 1.0.0
+Summary: Abstract payment contracts for OpenTrust payment providers
+Author-email: Novel Hut Studios <founder@novelhut.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Costder/opentrust
+Project-URL: Repository, https://github.com/Costder/opentrust
+Project-URL: Issues, https://github.com/Costder/opentrust/issues
+Keywords: opentrust,payments,escrow,ai-agents,tool-marketplace
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.7
+Requires-Dist: cryptography>=42
+
+# Payment Contracts
+
+This package defines the abstract payment interface for OpenTrust registries.
+
+Registry operators who want to enable paid tool access implement the `PaymentGateway`, `EscrowProvider`, and `SubscriptionManager` interfaces against the OpenTrust schema. The reference registry ships a mock checkout provider for demos and keeps production secrets out of source control.
+
+The schema driving these interfaces is in `passport-schema/commercial-status.schema.json` and `passport-schema/escrow.schema.json`.

opentrust_payment_contracts-1.0.0/opentrust_payment_contracts.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+opentrust_payment_contracts.egg-info/PKG-INFO
+opentrust_payment_contracts.egg-info/SOURCES.txt
+opentrust_payment_contracts.egg-info/dependency_links.txt
+opentrust_payment_contracts.egg-info/requires.txt
+opentrust_payment_contracts.egg-info/top_level.txt
+payment_contracts/__init__.py
+payment_contracts/models.py
+payment_contracts/interfaces/__init__.py
+payment_contracts/interfaces/escrow_interface.py
+payment_contracts/interfaces/payment_gateway.py
+payment_contracts/interfaces/subscription_manager.py
+payment_contracts/interfaces/verification_pricing.py
+tests/test_interfaces.py
+tests/test_models.py
+tests/test_quote_production_safety.py
+tests/test_quote_validation.py

opentrust_payment_contracts-1.0.0/opentrust_payment_contracts.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opentrust_payment_contracts-1.0.0/opentrust_payment_contracts.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pydantic>=2.7
+cryptography>=42

opentrust_payment_contracts-1.0.0/opentrust_payment_contracts.egg-info/top_level.txt

@@ -0,0 +1 @@
+payment_contracts

opentrust_payment_contracts-1.0.0/payment_contracts/__init__.py

@@ -0,0 +1,53 @@
+from payment_contracts.models import (
+    BillingPlan,
+    CheckoutSession,
+    DisputeCase,
+    EscrowId,
+    FeeKind,
+    FeeSchedule,
+    InMemoryNonceStore,
+    MarketplaceListing,
+    MarketplaceOrder,
+    NonceStore,
+    OpenTrustProduct,
+    PaymentQuote,
+    PaymentResult,
+    RefundResult,
+    RepoVerification,
+    Resolution,
+    Subscription,
+    WalletAccount,
+    WalletMode,
+    validate_quote,
+    validate_quote_expiration,
+    validate_quote_nonce,
+    validate_quote_signature,
+    validate_quote_wallet,
+)
+
+__all__ = [
+    "BillingPlan",
+    "CheckoutSession",
+    "DisputeCase",
+    "EscrowId",
+    "FeeKind",
+    "FeeSchedule",
+    "InMemoryNonceStore",
+    "MarketplaceListing",
+    "MarketplaceOrder",
+    "NonceStore",
+    "OpenTrustProduct",
+    "PaymentQuote",
+    "PaymentResult",
+    "RefundResult",
+    "RepoVerification",
+    "Resolution",
+    "Subscription",
+    "WalletAccount",
+    "WalletMode",
+    "validate_quote",
+    "validate_quote_expiration",
+    "validate_quote_nonce",
+    "validate_quote_signature",
+    "validate_quote_wallet",
+]

opentrust_payment_contracts-1.0.0/payment_contracts/interfaces/__init__.py

@@ -0,0 +1,6 @@
+from .escrow_interface import EscrowProvider
+from .payment_gateway import PaymentGateway
+from .subscription_manager import SubscriptionManager
+from .verification_pricing import VerificationPricing
+
+__all__ = ["EscrowProvider", "PaymentGateway", "SubscriptionManager", "VerificationPricing"]

opentrust_payment_contracts-1.0.0/payment_contracts/interfaces/escrow_interface.py

@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+from decimal import Decimal
+from payment_contracts.models import DisputeCase, EscrowId, Resolution
+
+
+class EscrowProvider(ABC):
+    @abstractmethod
+    def create_escrow(self, buyer_id: str, seller_id: str, amount: Decimal) -> EscrowId:
+        raise NotImplementedError
+
+    @abstractmethod
+    def deposit_address(self, escrow_id: str) -> str:
+        raise NotImplementedError
+
+    @abstractmethod
+    def release_funds(self, escrow_id: str) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    def refund_buyer(self, escrow_id: str) -> Resolution:
+        raise NotImplementedError
+
+    @abstractmethod
+    def dispute(self, escrow_id: str, reason: str) -> DisputeCase:
+        raise NotImplementedError
+
+    @abstractmethod
+    def resolve_dispute(self, case_id: str, winner: str) -> Resolution:
+        raise NotImplementedError

opentrust_payment_contracts-1.0.0/payment_contracts/interfaces/payment_gateway.py

@@ -0,0 +1,21 @@
+from abc import ABC, abstractmethod
+from decimal import Decimal
+from payment_contracts.models import CheckoutSession, PaymentResult, RefundResult
+
+
+class PaymentGateway(ABC):
+    @abstractmethod
+    def create_checkout(self, tool_id: str, plan: str, amount_usdc: Decimal) -> CheckoutSession:
+        raise NotImplementedError
+
+    @abstractmethod
+    def verify_payment(self, session_id: str) -> PaymentResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def process_refund(self, payment_id: str, amount: Decimal) -> RefundResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_balance(self) -> float:
+        raise NotImplementedError

opentrust_payment_contracts-1.0.0/payment_contracts/interfaces/subscription_manager.py

@@ -0,0 +1,16 @@
+from abc import ABC, abstractmethod
+from payment_contracts.models import BillingPlan, Subscription
+
+
+class SubscriptionManager(ABC):
+    @abstractmethod
+    def create_subscription(self, tool_id: str, plan: BillingPlan, customer: str) -> Subscription:
+        raise NotImplementedError
+
+    @abstractmethod
+    def cancel(self, subscription_id: str) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_active_subscriptions(self, tool_id: str) -> list[Subscription]:
+        raise NotImplementedError

opentrust_payment_contracts-1.0.0/payment_contracts/interfaces/verification_pricing.py

@@ -0,0 +1,16 @@
+from abc import ABC, abstractmethod
+from decimal import Decimal
+
+
+class VerificationPricing(ABC):
+    @abstractmethod
+    def get_verification_fee(self, tool_type: str) -> Decimal:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_listing_fee(self, category: str) -> Decimal:
+        raise NotImplementedError
+
+    @abstractmethod
+    def calculate_reviewer_payout(self, verification_id: str) -> Decimal:
+        raise NotImplementedError

opentrust_payment_contracts-1.0.0/payment_contracts/models.py

@@ -0,0 +1,281 @@
+"""Payment contracts models including signed payment quote validation and nonce replay protection."""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from decimal import Decimal
+from enum import Enum
+from typing import Protocol
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Legacy models (existing)
+# ---------------------------------------------------------------------------
+
+class FeeKind(str, Enum):
+    free = "free"
+    flat_fee = "flat_fee"
+    percentage = "percentage"
+
+
+class FeeSchedule(BaseModel):
+    kind: FeeKind
+    amount_usdc: Decimal | None = Field(default=None, ge=0)
+    percentage: Decimal | None = Field(default=None, ge=0, le=100)
+    notes: str | None = None
+
+
+class BillingPlan(BaseModel):
+    tier: str
+    interval: str = "one_time"
+    amount_usdc: Decimal = Field(ge=0)
+    fee_schedule: FeeSchedule | None = None
+
+
+class CheckoutSession(BaseModel):
+    session_id: str
+    tool_id: str
+    checkout_url: str
+    amount_usdc: Decimal = Field(ge=0)
+    status: str = "created"
+
+
+class PaymentResult(BaseModel):
+    payment_id: str
+    session_id: str
+    verified: bool
+    amount_usdc: Decimal = Field(ge=0)
+    status: str
+
+
+class RefundResult(BaseModel):
+    refund_id: str
+    payment_id: str
+    amount_usdc: Decimal = Field(ge=0)
+    status: str
+
+
+class Subscription(BaseModel):
+    subscription_id: str
+    tool_id: str
+    customer: str
+    plan: BillingPlan
+    active: bool = True
+
+
+class EscrowId(BaseModel):
+    escrow_id: str
+
+
+class DisputeCase(BaseModel):
+    case_id: str
+    escrow_id: str
+    reason: str
+    status: str = "open"
+
+
+class Resolution(BaseModel):
+    case_id: str
+    winner: str
+    released: bool
+
+
+class OpenTrustProduct(str, Enum):
+    trust_report = "trust_report"
+    verified_badge = "verified_badge"
+    monitoring_monthly = "monitoring_monthly"
+
+
+class WalletMode(str, Enum):
+    byo = "byo"
+    embedded = "embedded"
+
+
+class RepoVerification(BaseModel):
+    repo_id: str
+    installation_id: int
+    repo_full_name: str
+    branch: str
+    commit_sha: str
+    verified: bool = True
+
+
+class WalletAccount(BaseModel):
+    wallet_id: str
+    owner: str
+    address: str
+    mode: WalletMode
+    custody: str = "customer"
+
+
+class MarketplaceListing(BaseModel):
+    listing_id: str
+    seller_wallet_id: str
+    repo_id: str
+    title: str
+    price_usdc: Decimal = Field(gt=0)
+    currency: str = "USDC"
+    custody: str = "none"
+
+
+class MarketplaceOrder(BaseModel):
+    order_id: str
+    listing_id: str
+    buyer_wallet_id: str
+    seller_wallet_id: str
+    amount_usdc: Decimal = Field(gt=0)
+    currency: str = "USDC"
+    transaction_hash: str | None = None
+    custody: str = "none"
+
+
+# ---------------------------------------------------------------------------
+# PaymentQuote model (new)
+# ---------------------------------------------------------------------------
+
+class PaymentQuote(BaseModel):
+    """A cryptographically signed payment quote.
+
+    A tool operator signs a quote containing price, recipient, and a nonce.
+    The agent verifies the signature, checks expiration, and uses the nonce
+    to prevent replay attacks.
+    """
+
+    quote_id: str
+    passport_slug: str
+    version_hash: str
+    amount: Decimal = Field(ge=0)
+    currency: str = "USDC"
+    chain: str = "base"
+    recipient_wallet: str
+    expires_at: datetime
+    nonce: str
+    terms_hash: str | None = None
+    proof_requirement: str = "hash_match"
+    signature: str = ""
+
+    def signing_payload(self) -> str:
+        """Return the canonical string that gets signed.
+
+        Excludes the signature field itself. Uses a sorted JSON serialization
+        so the payload is deterministic regardless of field order.
+        """
+        data = self.model_dump(mode="json", exclude={"signature"})
+        data["amount"] = str(self.amount)
+        data["expires_at"] = self.expires_at.isoformat()
+        return json.dumps(data, sort_keys=True, separators=(",", ":"))
+
+
+# ---------------------------------------------------------------------------
+# Nonce store (replay protection)
+# ---------------------------------------------------------------------------
+
+class NonceStore(Protocol):
+    """Protocol for nonce storage backends."""
+
+    def seen(self, nonce: str) -> bool: ...
+
+    def mark_seen(self, nonce: str) -> None: ...
+
+
+class InMemoryNonceStore:
+    """Thread-safe in-memory nonce store for replay protection."""
+
+    def __init__(self) -> None:
+        self._seen: set[str] = set()
+
+    def seen(self, nonce: str) -> bool:
+        return nonce in self._seen
+
+    def mark_seen(self, nonce: str) -> None:
+        self._seen.add(nonce)
+
+
+# ---------------------------------------------------------------------------
+# Validation functions
+# ---------------------------------------------------------------------------
+
+def validate_quote_signature(
+    quote: PaymentQuote,
+    public_key: Ed25519PublicKey,
+) -> bool:
+    """Verify the Ed25519 signature on a PaymentQuote.
+
+    Returns True if the signature is valid, False otherwise.
+    """
+    if not quote.signature:
+        return False
+    try:
+        sig = bytes.fromhex(quote.signature)
+        message = quote.signing_payload().encode("utf-8")
+        public_key.verify(sig, message)
+        return True
+    except Exception:
+        return False
+
+
+def validate_quote_expiration(quote: PaymentQuote) -> bool:
+    """Check that the quote has not expired.
+
+    Returns True if expires_at is in the future, False if expired.
+    """
+    return quote.expires_at > datetime.now(timezone.utc)
+
+
+def validate_quote_nonce(
+    quote: PaymentQuote,
+    nonce_store: NonceStore,
+) -> bool:
+    """Check that the nonce hasn't been used before.
+
+    Returns True if the nonce is fresh (first use), False if replayed.
+    Marks the nonce as seen on first use.
+    """
+    if nonce_store.seen(quote.nonce):
+        return False
+    nonce_store.mark_seen(quote.nonce)
+    return True
+
+
+def validate_quote_wallet(
+    quote: PaymentQuote,
+    expected_wallet: str,
+) -> bool:
+    """Check that the quote's recipient_wallet matches the expected wallet.
+
+    Returns True if wallets match, False otherwise.
+    """
+    return quote.recipient_wallet == expected_wallet
+
+
+def validate_quote(
+    quote: PaymentQuote,
+    public_key: Ed25519PublicKey,
+    nonce_store: NonceStore,
+    expected_wallet: str,
+) -> list[str]:
+    """Run all validation checks on a signed PaymentQuote.
+
+    Returns a list of error messages. An empty list means the quote is valid.
+    The nonce is burned only after signature, expiration, and wallet checks pass;
+    otherwise an attacker could submit a malformed quote first and DoS the real
+    quote by consuming its nonce.
+    """
+    errors: list[str] = []
+
+    if not validate_quote_signature(quote, public_key):
+        errors.append("invalid signature")
+
+    if not validate_quote_expiration(quote):
+        errors.append("quote expired")
+
+    if not validate_quote_wallet(quote, expected_wallet):
+        errors.append("wallet mismatch")
+
+    if not errors and not validate_quote_nonce(quote, nonce_store):
+        errors.append("nonce replay detected")
+
+    return errors

opentrust_payment_contracts-1.0.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opentrust-payment-contracts"
+version = "1.0.0"
+description = "Abstract payment contracts for OpenTrust payment providers"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Novel Hut Studios", email = "founder@novelhut.net" }]
+keywords = ["opentrust", "payments", "escrow", "ai-agents", "tool-marketplace"]
+dependencies = ["pydantic>=2.7", "cryptography>=42"]
+
+[project.urls]
+Homepage = "https://github.com/Costder/opentrust"
+Repository = "https://github.com/Costder/opentrust"
+Issues = "https://github.com/Costder/opentrust/issues"
+
+[tool.setuptools]
+packages = ["payment_contracts", "payment_contracts.interfaces"]

opentrust_payment_contracts-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

opentrust_payment_contracts-1.0.0/tests/test_interfaces.py

@@ -0,0 +1,58 @@
+import pytest
+from decimal import Decimal
+from payment_contracts.interfaces.escrow_interface import EscrowProvider
+from payment_contracts.interfaces.payment_gateway import PaymentGateway
+
+
+class DummyGateway(PaymentGateway):
+    def create_checkout(self, tool_id, plan, amount_usdc):
+        return super().create_checkout(tool_id, plan, amount_usdc)
+
+    def verify_payment(self, session_id):
+        return super().verify_payment(session_id)
+
+    def process_refund(self, payment_id, amount):
+        return super().process_refund(payment_id, amount)
+
+    def get_balance(self):
+        return super().get_balance()
+
+
+class DummyEscrowProvider(EscrowProvider):
+    def create_escrow(self, buyer_id, seller_id, amount):
+        return super().create_escrow(buyer_id, seller_id, amount)
+
+    def deposit_address(self, escrow_id):
+        return super().deposit_address(escrow_id)
+
+    def release_funds(self, escrow_id):
+        return super().release_funds(escrow_id)
+
+    def refund_buyer(self, escrow_id):
+        return super().refund_buyer(escrow_id)
+
+    def dispute(self, escrow_id, reason):
+        return super().dispute(escrow_id, reason)
+
+    def resolve_dispute(self, case_id, winner):
+        return super().resolve_dispute(case_id, winner)
+
+
+def test_payment_gateway_methods_raise_not_implemented():
+    gateway = DummyGateway()
+    with pytest.raises(NotImplementedError):
+        gateway.create_checkout("tool", "verification", Decimal("10"))
+
+
+def test_escrow_provider_methods_raise_not_implemented():
+    provider = DummyEscrowProvider()
+    with pytest.raises(NotImplementedError):
+        provider.create_escrow("buyer", "seller", Decimal("10"))
+    with pytest.raises(NotImplementedError):
+        provider.deposit_address("escrow_1")
+    with pytest.raises(NotImplementedError):
+        provider.release_funds("escrow_1")
+    with pytest.raises(NotImplementedError):
+        provider.refund_buyer("escrow_1")
+    with pytest.raises(NotImplementedError):
+        provider.dispute("escrow_1", "missing delivery")

opentrust_payment_contracts-1.0.0/tests/test_models.py

@@ -0,0 +1,52 @@
+from decimal import Decimal
+from payment_contracts.models import (
+    BillingPlan,
+    CheckoutSession,
+    FeeSchedule,
+    MarketplaceListing,
+    MarketplaceOrder,
+    RepoVerification,
+    WalletAccount,
+)
+
+
+def test_checkout_session_validation():
+    session = CheckoutSession(session_id="s1", tool_id="tool", checkout_url="https://example.com", amount_usdc=Decimal("10"))
+    assert session.status == "created"
+
+
+def test_billing_plan_accepts_fee_schedule():
+    plan = BillingPlan(tier="verification", amount_usdc=Decimal("25"), fee_schedule=FeeSchedule(kind="flat_fee", amount_usdc=Decimal("25")))
+    assert plan.fee_schedule is not None
+
+
+def test_marketplace_contract_models_are_non_custodial():
+    repo = RepoVerification(
+        repo_id="repo_1",
+        installation_id=123,
+        repo_full_name="octo/tool",
+        branch="main",
+        commit_sha="abc1234567",
+    )
+    wallet = WalletAccount(
+        wallet_id="wallet_1",
+        owner="seller",
+        address="0x1111111111111111111111111111111111111111",
+        mode="byo",
+    )
+    listing = MarketplaceListing(
+        listing_id="listing_1",
+        seller_wallet_id=wallet.wallet_id,
+        repo_id=repo.repo_id,
+        title="Verified package",
+        price_usdc=Decimal("10"),
+    )
+    order = MarketplaceOrder(
+        order_id="order_1",
+        listing_id=listing.listing_id,
+        buyer_wallet_id="wallet_2",
+        seller_wallet_id=wallet.wallet_id,
+        amount_usdc=Decimal("10"),
+    )
+    assert listing.custody == "none"
+    assert order.custody == "none"

opentrust_payment_contracts-1.0.0/tests/test_quote_production_safety.py

@@ -0,0 +1,57 @@
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from payment_contracts.models import InMemoryNonceStore, PaymentQuote, validate_quote
+
+
+def _signed_quote(private_key, **overrides):
+    data = {
+        "quote_id": "quote-1",
+        "passport_slug": "demo-tool",
+        "version_hash": "sha256:abc123",
+        "amount": Decimal("0.25"),
+        "currency": "USDC",
+        "chain": "base",
+        "recipient_wallet": "0x1111111111111111111111111111111111111111",
+        "expires_at": datetime.now(timezone.utc) + timedelta(minutes=5),
+        "nonce": "nonce-1",
+        "terms_hash": "sha256:terms",
+        "proof_requirement": "hash_match",
+    }
+    data.update(overrides)
+    quote = PaymentQuote(**data)
+    signature = private_key.sign(quote.signing_payload().encode("utf-8")).hex()
+    return quote.model_copy(update={"signature": signature})
+
+
+def test_payment_quote_requires_delivery_proof_requirement():
+    private_key = Ed25519PrivateKey.generate()
+    quote = _signed_quote(private_key)
+
+    assert quote.proof_requirement == "hash_match"
+
+
+def test_invalid_quote_does_not_burn_nonce():
+    private_key = Ed25519PrivateKey.generate()
+    public_key = private_key.public_key()
+    nonce_store = InMemoryNonceStore()
+    quote = _signed_quote(private_key, nonce="nonce-dos")
+    bad_quote = quote.model_copy(update={"signature": "00"})
+
+    errors = validate_quote(
+        bad_quote,
+        public_key,
+        nonce_store,
+        expected_wallet="0x1111111111111111111111111111111111111111",
+    )
+    assert "invalid signature" in errors
+    assert nonce_store.seen("nonce-dos") is False
+
+    assert validate_quote(
+        quote,
+        public_key,
+        nonce_store,
+        expected_wallet="0x1111111111111111111111111111111111111111",
+    ) == []

opentrust_payment_contracts-1.0.0/tests/test_quote_validation.py

@@ -0,0 +1,445 @@
+"""Tests for signed payment quote validation and nonce replay protection.
+
+Strict TDD: Write failing tests first, then implement minimal code.
+"""
+from __future__ import annotations
+
+import time
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+
+import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from payment_contracts.models import PaymentQuote
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def signer_keys():
+    """Generate a fresh Ed25519 key pair for each test."""
+    private_key = Ed25519PrivateKey.generate()
+    public_key = private_key.public_key()
+    return private_key, public_key
+
+
+@pytest.fixture
+def valid_quote_dict(signer_keys):
+    """Return a valid unsigned quote dict (no signature yet)."""
+    _, public_key = signer_keys
+    return {
+        "quote_id": "qt_abc123",
+        "passport_slug": "github-search-mcp",
+        "version_hash": "v1.0.0",
+        "amount": Decimal("19.00"),
+        "currency": "USDC",
+        "chain": "base",
+        "recipient_wallet": "0x1234567890abcdef1234567890abcdef12345678",
+        "expires_at": datetime.now(timezone.utc) + timedelta(hours=1),
+        "nonce": "nonce-001",
+        "terms_hash": "sha256:abc123def456",
+        "signature": "",
+    }
+
+
+@pytest.fixture
+def signed_quote(valid_quote_dict, signer_keys):
+    """Create a fully signed PaymentQuote."""
+    private_key, public_key = signer_keys
+    quote = PaymentQuote(**valid_quote_dict)
+    message = quote.signing_payload().encode("utf-8")
+    sig = private_key.sign(message)
+    quote.signature = sig.hex()
+    return quote, public_key
+
+
+# ---------------------------------------------------------------------------
+# Model tests
+# ---------------------------------------------------------------------------
+
+class TestPaymentQuoteModel:
+    """PaymentQuote Pydantic model construction."""
+
+    def test_minimal_quote_construction(self, valid_quote_dict):
+        """A quote with all required fields can be constructed."""
+        quote = PaymentQuote(**valid_quote_dict)
+        assert quote.quote_id == "qt_abc123"
+        assert quote.passport_slug == "github-search-mcp"
+        assert quote.amount == Decimal("19.00")
+        assert quote.currency == "USDC"
+        assert quote.chain == "base"
+
+    def test_default_values(self):
+        """Defaults: currency='USDC', chain='base'."""
+        now = datetime.now(timezone.utc)
+        quote = PaymentQuote(
+            quote_id="qt_1",
+            passport_slug="slug",
+            version_hash="v1",
+            amount=Decimal("10"),
+            recipient_wallet="0xabc",
+            expires_at=now,
+            nonce="n1",
+        )
+        assert quote.currency == "USDC"
+        assert quote.chain == "base"
+        assert quote.terms_hash is None
+        assert quote.signature == ""
+
+    def test_amount_must_be_positive(self):
+        """Amount must be >= 0."""
+        now = datetime.now(timezone.utc)
+        with pytest.raises(ValueError):
+            PaymentQuote(
+                quote_id="qt_1",
+                passport_slug="slug",
+                version_hash="v1",
+                amount=Decimal("-1"),
+                recipient_wallet="0xabc",
+                expires_at=now,
+                nonce="n1",
+            )
+
+    def test_expires_at_must_be_future(self, valid_quote_dict):
+        """Model allows past expires_at — validation is separate."""
+        past = datetime.now(timezone.utc) - timedelta(hours=1)
+        quote = PaymentQuote(
+            quote_id="qt_1",
+            passport_slug="slug",
+            version_hash="v1",
+            amount=Decimal("10"),
+            recipient_wallet="0xabc",
+            expires_at=past,
+            nonce="n1",
+        )
+        assert quote.expires_at < datetime.now(timezone.utc)
+
+    def test_signing_payload_is_deterministic(self, valid_quote_dict):
+        """Same data produces same signing payload."""
+        q1 = PaymentQuote(**valid_quote_dict)
+        q2 = PaymentQuote(**valid_quote_dict)
+        assert q1.signing_payload() == q2.signing_payload()
+
+    def test_signing_payload_excludes_signature(self, valid_quote_dict):
+        """signing_payload must NOT include the signature field."""
+        q1 = PaymentQuote(**valid_quote_dict)
+        q1.signature = ""
+        q2 = PaymentQuote(**valid_quote_dict)
+        q2.signature = "DEADBEEF"
+        assert q1.signing_payload() == q2.signing_payload()
+
+    def test_signing_payload_format(self, valid_quote_dict):
+        """signing_payload returns a canonical JSON string."""
+        quote = PaymentQuote(**valid_quote_dict)
+        payload = quote.signing_payload()
+        assert isinstance(payload, str)
+        assert len(payload) > 0
+        # Should contain key fields
+        assert "qt_abc123" in payload
+        assert "github-search-mcp" in payload
+        assert "nonce-001" in payload
+
+    def test_sign_and_verify_roundtrip(self, valid_quote_dict, signer_keys):
+        """Sign a quote and verify it using the signer's public key."""
+        private_key, public_key = signer_keys
+        quote = PaymentQuote(**valid_quote_dict)
+        message = quote.signing_payload().encode("utf-8")
+        sig = private_key.sign(message)
+        quote.signature = sig.hex()
+        public_key.verify(sig, message)
+        assert quote.signature == sig.hex()
+
+
+# ---------------------------------------------------------------------------
+# Quote validation tests
+# ---------------------------------------------------------------------------
+
+class TestQuoteSignatureValidation:
+    """Verify Ed25519 signature on PaymentQuote."""
+
+    def test_valid_signature_passes(self, signed_quote):
+        """A correctly signed quote passes signature validation."""
+        quote, public_key = signed_quote
+        from payment_contracts.models import validate_quote_signature
+        result = validate_quote_signature(quote, public_key)
+        assert result is True
+
+    def test_invalid_signature_fails(self, signed_quote):
+        """A quote with a tampered signature fails."""
+        quote, public_key = signed_quote
+        quote.signature = "deadbeef" * 8  # garbage
+        from payment_contracts.models import validate_quote_signature
+        result = validate_quote_signature(quote, public_key)
+        assert result is False
+
+    def test_tampered_payload_fails(self, signed_quote):
+        """A quote whose data was altered after signing fails validation."""
+        quote, public_key = signed_quote
+        quote.amount = Decimal("999.99")  # tamper
+        from payment_contracts.models import validate_quote_signature
+        result = validate_quote_signature(quote, public_key)
+        assert result is False
+
+    def test_missing_signature_fails(self, valid_quote_dict, signer_keys):
+        """A quote with empty signature fails."""
+        _, public_key = signer_keys
+        quote = PaymentQuote(**valid_quote_dict)
+        quote.signature = ""
+        from payment_contracts.models import validate_quote_signature
+        result = validate_quote_signature(quote, public_key)
+        assert result is False
+
+    def test_wrong_public_key_fails(self, signed_quote):
+        """Verifying with a different public key fails."""
+        quote, _ = signed_quote
+        wrong_key = Ed25519PrivateKey.generate().public_key()
+        from payment_contracts.models import validate_quote_signature
+        result = validate_quote_signature(quote, wrong_key)
+        assert result is False
+
+
+class TestQuoteExpirationValidation:
+    """Reject expired quotes."""
+
+    def test_future_quote_passes(self, signed_quote):
+        """A quote expiring in the future passes."""
+        quote, _ = signed_quote
+        from payment_contracts.models import validate_quote_expiration
+        result = validate_quote_expiration(quote)
+        assert result is True
+
+    def test_expired_quote_fails(self, valid_quote_dict, signer_keys):
+        """A quote whose expires_at is in the past fails."""
+        private_key, _ = signer_keys
+        past = datetime.now(timezone.utc) - timedelta(seconds=1)
+        valid_quote_dict["expires_at"] = past
+        quote = PaymentQuote(**valid_quote_dict)
+        message = quote.signing_payload().encode("utf-8")
+        sig = private_key.sign(message)
+        quote.signature = sig.hex()
+        from payment_contracts.models import validate_quote_expiration
+        result = validate_quote_expiration(quote)
+        assert result is False
+
+    def test_just_expired_quote_fails(self, valid_quote_dict, signer_keys):
+        """A quote that expired 1 second ago fails."""
+        private_key, _ = signer_keys
+        just_past = datetime.now(timezone.utc) - timedelta(seconds=1)
+        valid_quote_dict["expires_at"] = just_past
+        quote = PaymentQuote(**valid_quote_dict)
+        message = quote.signing_payload().encode("utf-8")
+        sig = private_key.sign(message)
+        quote.signature = sig.hex()
+        from payment_contracts.models import validate_quote_expiration
+        result = validate_quote_expiration(quote)
+        assert result is False
+
+    def test_near_future_quote_passes(self, valid_quote_dict, signer_keys):
+        """A quote expiring just slightly in the future passes."""
+        private_key, _ = signer_keys
+        near_future = datetime.now(timezone.utc) + timedelta(seconds=5)
+        valid_quote_dict["expires_at"] = near_future
+        quote = PaymentQuote(**valid_quote_dict)
+        message = quote.signing_payload().encode("utf-8")
+        sig = private_key.sign(message)
+        quote.signature = sig.hex()
+        from payment_contracts.models import validate_quote_expiration
+        result = validate_quote_expiration(quote)
+        assert result is True
+
+
+class TestNonceReplayProtection:
+    """Reject replayed nonces."""
+
+    @pytest.fixture
+    def nonce_store(self):
+        """Simple in-memory nonce store."""
+        from payment_contracts.models import InMemoryNonceStore
+        return InMemoryNonceStore()
+
+    def test_fresh_nonce_passes(self, signed_quote, nonce_store):
+        """A never-before-seen nonce passes."""
+        quote, _ = signed_quote
+        from payment_contracts.models import validate_quote_nonce
+        result = validate_quote_nonce(quote, nonce_store)
+        assert result is True
+
+    def test_replayed_nonce_fails(self, signed_quote, nonce_store):
+        """The same nonce used twice fails."""
+        quote, _ = signed_quote
+        from payment_contracts.models import validate_quote_nonce
+        # First use — should pass
+        assert validate_quote_nonce(quote, nonce_store) is True
+        # Second use — should fail (replay)
+        result = validate_quote_nonce(quote, nonce_store)
+        assert result is False
+
+    def test_different_nonces_pass(self, valid_quote_dict, signer_keys, nonce_store):
+        """Different nonces are allowed."""
+        private_key, _ = signer_keys
+        from payment_contracts.models import validate_quote_nonce
+
+        for i in range(3):
+            d = dict(valid_quote_dict)
+            d["nonce"] = f"nonce-{i:03d}"
+            quote = PaymentQuote(**d)
+            message = quote.signing_payload().encode("utf-8")
+            sig = private_key.sign(message)
+            quote.signature = sig.hex()
+            assert validate_quote_nonce(quote, nonce_store) is True
+
+    def test_nonce_store_persistence(self, signed_quote, nonce_store):
+        """Nonce remains seen across calls."""
+        quote, _ = signed_quote
+        from payment_contracts.models import validate_quote_nonce
+        assert validate_quote_nonce(quote, nonce_store) is True
+        assert validate_quote_nonce(quote, nonce_store) is False
+
+    def test_seen_method_on_store(self, signed_quote, nonce_store):
+        """NonceStore.seen() correctly reports nonce state."""
+        quote, _ = signed_quote
+        from payment_contracts.models import validate_quote_nonce
+        assert nonce_store.seen(quote.nonce) is False
+        validate_quote_nonce(quote, nonce_store)
+        assert nonce_store.seen(quote.nonce) is True
+
+
+class TestQuoteWalletValidation:
+    """Wallet must match expected recipient."""
+
+    def test_wallet_matches_passes(self, signed_quote):
+        """When recipient_wallet matches expected, passes."""
+        quote, _ = signed_quote
+        from payment_contracts.models import validate_quote_wallet
+        result = validate_quote_wallet(quote, quote.recipient_wallet)
+        assert result is True
+
+    def test_wallet_mismatch_fails(self, signed_quote):
+        """When recipient_wallet differs from expected, fails."""
+        quote, _ = signed_quote
+        from payment_contracts.models import validate_quote_wallet
+        result = validate_quote_wallet(quote, "0x9999999999999999999999999999999999999999")
+        assert result is False
+
+    def test_case_sensitive_wallet_check(self, signed_quote):
+        """Wallet check is case-sensitive."""
+        quote, _ = signed_quote
+        from payment_contracts.models import validate_quote_wallet
+        wrong_case = quote.recipient_wallet.upper()
+        if wrong_case != quote.recipient_wallet:
+            result = validate_quote_wallet(quote, wrong_case)
+            assert result is False
+
+
+# ---------------------------------------------------------------------------
+# Full validation pipeline tests
+# ---------------------------------------------------------------------------
+
+class TestFullQuoteValidation:
+    """End-to-end validation combining all checks."""
+
+    @pytest.fixture
+    def nonce_store(self):
+        from payment_contracts.models import InMemoryNonceStore
+        return InMemoryNonceStore()
+
+    def test_complete_valid_quote_passes(self, signed_quote, nonce_store):
+        """A fully valid quote passes all checks."""
+        quote, public_key = signed_quote
+        from payment_contracts.models import validate_quote
+        errors = validate_quote(
+            quote=quote,
+            public_key=public_key,
+            nonce_store=nonce_store,
+            expected_wallet=quote.recipient_wallet,
+        )
+        assert errors == []
+
+    def test_expired_quote_rejected(self, valid_quote_dict, signer_keys, nonce_store):
+        """Expired quote fails full validation."""
+        private_key, public_key = signer_keys
+        past = datetime.now(timezone.utc) - timedelta(minutes=5)
+        valid_quote_dict["expires_at"] = past
+        quote = PaymentQuote(**valid_quote_dict)
+        message = quote.signing_payload().encode("utf-8")
+        sig = private_key.sign(message)
+        quote.signature = sig.hex()
+
+        from payment_contracts.models import validate_quote
+        errors = validate_quote(
+            quote=quote,
+            public_key=public_key,
+            nonce_store=nonce_store,
+            expected_wallet=quote.recipient_wallet,
+        )
+        assert "expired" in " ".join(errors).lower()
+
+    def test_bad_signature_rejected(self, valid_quote_dict, signer_keys, nonce_store):
+        """Tampered signature fails full validation."""
+        _, public_key = signer_keys
+        quote = PaymentQuote(**valid_quote_dict)
+        quote.signature = "bad" * 20
+        from payment_contracts.models import validate_quote
+        errors = validate_quote(
+            quote=quote,
+            public_key=public_key,
+            nonce_store=nonce_store,
+            expected_wallet=quote.recipient_wallet,
+        )
+        assert "signature" in " ".join(errors).lower()
+
+    def test_replayed_nonce_rejected(self, signed_quote, nonce_store):
+        """Replayed nonce fails full validation."""
+        quote, public_key = signed_quote
+        from payment_contracts.models import validate_quote
+        # First use
+        errors1 = validate_quote(
+            quote=quote,
+            public_key=public_key,
+            nonce_store=nonce_store,
+            expected_wallet=quote.recipient_wallet,
+        )
+        assert errors1 == []
+        # Second use (replay)
+        errors2 = validate_quote(
+            quote=quote,
+            public_key=public_key,
+            nonce_store=nonce_store,
+            expected_wallet=quote.recipient_wallet,
+        )
+        assert "nonce" in " ".join(errors2).lower()
+
+    def test_wallet_mismatch_rejected(self, signed_quote, nonce_store):
+        """Wrong wallet fails full validation."""
+        quote, public_key = signed_quote
+        from payment_contracts.models import validate_quote
+        errors = validate_quote(
+            quote=quote,
+            public_key=public_key,
+            nonce_store=nonce_store,
+            expected_wallet="0x0000000000000000000000000000000000000000",
+        )
+        assert "wallet" in " ".join(errors).lower()
+
+    def test_multiple_failures_reported(self, valid_quote_dict, signer_keys, nonce_store):
+        """Multiple validation errors are reported together."""
+        private_key, public_key = signer_keys
+        past = datetime.now(timezone.utc) - timedelta(hours=2)
+        valid_quote_dict["expires_at"] = past
+        quote = PaymentQuote(**valid_quote_dict)
+        message = quote.signing_payload().encode("utf-8")
+        sig = private_key.sign(message)
+        quote.signature = sig.hex()
+        quote.signature = "bad" * 20  # Also tamper signature
+
+        from payment_contracts.models import validate_quote
+        errors = validate_quote(
+            quote=quote,
+            public_key=public_key,
+            nonce_store=nonce_store,
+            expected_wallet="wrong_wallet",
+        )
+        assert len(errors) >= 2