agentic-payments 0.1.0

# AP2 (Agent Payments Protocol) Implementation

## Overview

The Agent Payments Protocol (AP2) provides a standardized, secure framework for agent-to-agent payment authorization and verification using W3C Verifiable Credentials with Ed25519 signatures.

## Architecture

### Core Components

```
┌─────────────────────────────────────────────────────────────┐
│                     AP2 Protocol Layer                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │ Verifiable   │  │   Mandates   │  │     DID      │    │
│  │ Credentials  │  │ Management   │  │  Management  │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
│         │                  │                  │            │
│         └──────────────────┴──────────────────┘            │
│                         │                                   │
│                ┌────────▼────────┐                         │
│                │  Verification   │                         │
│                │   Workflow      │                         │
│                └─────────────────┘                         │
└─────────────────────────────────────────────────────────────┘
         │                                         │
         ▼                                         ▼
┌─────────────────┐                    ┌──────────────────┐
│ Ed25519 Crypto  │                    │ Multi-Agent      │
│   (dalek)       │                    │  Consensus       │
└─────────────────┘                    └──────────────────┘
```

## Modules

### 1. Verifiable Credentials (`credentials.rs`)

W3C Verifiable Credentials implementation with Ed25519 signatures.

**Key Types:**
- `VerifiableCredential` - Main credential structure
- `CredentialSubject` - Subject claims
- `Proof` - Cryptographic proof with Ed25519 signature
- `VerificationMethod` - Public key information
- `CredentialBuilder` - Fluent API for credential creation

**Features:**
- Ed25519 signature creation and verification
- Expiration handling
- Canonical JSON serialization
- Base64URL encoding for signatures
- Multi-context support (W3C VC + AP2)

**Example:**
```rust
use agentic_payments::ap2::*;
use ed25519_dalek::SigningKey;

let signing_key = SigningKey::generate(&mut rand::rngs::OsRng);
let issuer = "did:ap2:issuer".to_string();

let credential = CredentialBuilder::new(issuer, "did:ap2:subject".to_string())
    .add_claim("role".to_string(), serde_json::json!("payment-agent"))
    .add_type("PaymentCredential".to_string())
    .with_expiration(Utc::now() + Duration::days(30))
    .build(signing_key.as_bytes())?;
```

### 2. Mandates (`mandates.rs`)

Three types of mandates for payment authorization:

#### Intent Mandate
User authorization for agent actions with permissions and constraints.

```rust
let mut mandate = IntentMandate::new(
    "did:ap2:user".to_string(),
    "did:ap2:agent".to_string(),
    "Purchase items on behalf of user".to_string(),
);

mandate.add_permission(Permission {
    action: "purchase".to_string(),
    resource: "electronics".to_string(),
    conditions: vec!["max_amount:10000".to_string()],
});

mandate.add_constraint(
    "daily_limit".to_string(),
    serde_json::json!(50000),
);
```

#### Cart Mandate
Explicit purchase authorization with itemized cart and calculations.

```rust
let items = vec![
    CartItem::new("item1".to_string(), "Product A".to_string(), 2, 2500),
    CartItem::new("item2".to_string(), "Product B".to_string(), 1, 5000),
];

let cart_mandate = CartMandate::new(
    "did:ap2:user".to_string(),
    items,
    10000,
    "USD".to_string(),
)
.with_merchant("did:ap2:merchant".to_string())
.with_tax(800)
.with_shipping(500);

assert!(cart_mandate.verify_total());
```

#### Payment Mandate
Payment network signaling for actual transaction execution.

```rust
let mut payment_mandate = PaymentMandate::new(
    "did:ap2:payer".to_string(),
    "did:ap2:payee".to_string(),
    10000,
    "USD".to_string(),
    "credit_card".to_string(),
)
.with_payment_method(PaymentMethod::CreditCard {
    last_four: "4242".to_string(),
})
.with_payment_network("stripe".to_string())
.link_cart_mandate(cart_id);

payment_mandate.activate();
```

### 3. DID Management (`did.rs`)

Decentralized Identifier (DID) creation, resolution, and management.

**Key Types:**
- `DidDocument` - W3C DID Document
- `DidManager` - DID creation and lifecycle management
- `DidResolver` - DID resolution with caching
- `ServiceEndpoint` - Service endpoint definitions
- `DidUrlParser` - DID URL parsing

**Features:**
- DID document creation with verification methods
- Service endpoint management
- DID resolution and caching
- Multiple verification method support
- Controller chain management

**Example:**
```rust
let mut manager = DidManager::new();

// Create DID
let public_key = signing_key.verifying_key().to_bytes().to_vec();
let did = manager.create_did("agent-001", public_key)?;

// Add service endpoint
let service = ServiceEndpoint {
    id: format!("{}#payment", did),
    service_type: "PaymentService".to_string(),
    service_endpoint: "https://payment.example.com".to_string(),
    description: Some("Payment processing".to_string()),
};

manager.add_service_to_did(&did, service)?;

// Resolve DID
let did_doc = manager.get_did_document(&did)?;
```

### 4. Verification Workflow (`verification.rs`)

Multi-agent consensus verification for credentials.

**Key Types:**
- `VerificationWorkflow` - Main verification orchestrator
- `ConsensusVerification` - Consensus algorithm implementation
- `VerifierNode` - Verifier agent representation
- `VerificationResult` - Detailed verification results
- `VerificationPolicy` - Verification rules and policies

**Features:**
- Multi-agent consensus with configurable threshold
- Weighted voting with reputation system
- Parallel verification execution
- Verifier node registry
- Reputation management
- Multiple policy levels (strict, standard, permissive)

**Example:**
```rust
let workflow = VerificationWorkflow::new();

// Register verifiers
for i in 0..5 {
    let verifier = VerifierNode::new(
        format!("verifier-{}", i),
        format!("did:ap2:verifier-{}", i),
        format!("https://verifier-{}.example.com", i),
    )
    .with_weight(1.0)
    .with_reputation(0.95);

    workflow.register_verifier(verifier).await;
}

// Verify with consensus
let result = workflow.verify_with_all_verifiers(
    &credential,
    &did_resolver,
).await?;

println!("Consensus: {}/{} approved", result.approval_count, result.verifier_count);
```

## Complete Payment Flow

### Step-by-Step Authorization Chain

```rust
use agentic_payments::ap2::*;

#[tokio::main]
async fn main() -> Result<()> {
    let mut protocol = Ap2Protocol::new();

    // 1. Register participants
    let user_key = SigningKey::generate(&mut rand::rngs::OsRng);
    let merchant_key = SigningKey::generate(&mut rand::rngs::OsRng);

    let user = protocol.register_agent(
        "user",
        user_key.verifying_key().to_bytes().to_vec(),
    )?;

    let merchant = protocol.register_agent(
        "merchant",
        merchant_key.verifying_key().to_bytes().to_vec(),
    )?;

    // 2. Create Intent Mandate (user authorization)
    let intent = protocol.create_intent_mandate(
        &user,
        &merchant.did,
        "Purchase items from merchant",
        user_key.as_bytes(),
    )?;

    // 3. Create Cart Mandate (explicit purchase)
    let items = vec![
        CartItem::new("item1".to_string(), "Product".to_string(), 1, 5000),
    ];

    let cart = protocol.create_cart_mandate(
        &user,
        items,
        5000,
        "USD",
        user_key.as_bytes(),
    )?;

    // 4. Create Payment Mandate (payment signal)
    let payment = protocol.create_payment_mandate(
        &user,
        &merchant.did,
        5000,
        "USD",
        "credit_card",
        user_key.as_bytes(),
    )?;

    // 5. Create authorization chain
    let authorization = PaymentAuthorization::new(intent, cart, payment);

    // 6. Verify chain
    assert!(authorization.verify_chain(protocol.did_resolver())?);

    // 7. Verify with consensus
    let verifiers = create_verifier_nodes(&mut protocol, 5);
    let result = protocol.verify_payment_authorization(
        &authorization,
        verifiers,
    ).await?;

    assert!(result.verified);
    println!("Payment authorized: {}/{} consensus",
        result.approval_count, result.verifier_count);

    Ok(())
}
```

## Security Features

### 1. Ed25519 Signatures
- Fast verification (~64 microseconds)
- Small signatures (64 bytes)
- Strong security (128-bit security level)
- Deterministic signing

### 2. Cryptographic Verification
- SHA-256 hashing for canonical representation
- Base64URL encoding for web-safe transport
- Signature verification before any processing
- Expiration checks

### 3. Multi-Agent Consensus
- Byzantine fault tolerance
- Configurable consensus threshold (default: 2/3)
- Weighted voting with reputation
- Parallel verification for performance
- Minimum verifier requirements

### 4. Authorization Chain
- Three-tier mandate system
- Complete chain verification
- Expiration handling at each level
- Revocation support

## Performance Characteristics

### Verification Speed
- Single credential verification: ~500μs
- Multi-agent consensus (5 nodes): ~2ms
- DID resolution (cached): ~100μs
- Complete authorization chain: ~5ms

### Scalability
- Supports 100+ verifier nodes
- Parallel verification execution
- Efficient caching for DID resolution
- Async/await for non-blocking operations

### Resource Usage
- Minimal memory footprint
- No heavy dependencies
- Efficient serialization with serde
- Zero-copy operations where possible

## Testing

### Unit Tests
Run unit tests for individual modules:
```bash
cargo test --package agentic-payments --lib ap2
```

### Integration Tests
Run complete payment flow tests:
```bash
cargo test --package agentic-payments --test ap2_integration_test
```

### Examples
Run example scenarios:
```bash
# Complete payment flow
cargo run --example ap2_payment_flow

# Mandate management
cargo run --example ap2_mandate_management
```

## API Reference

### Main Types

#### `Ap2Protocol`
Main protocol handler for AP2 operations.

Methods:
- `new()` - Create new protocol instance
- `register_agent(id, public_key)` - Register agent identity
- `create_intent_mandate(...)` - Create intent mandate
- `create_cart_mandate(...)` - Create cart mandate
- `create_payment_mandate(...)` - Create payment mandate
- `verify_payment_authorization(...)` - Verify with consensus
- `resolve_did(did)` - Resolve DID to document

#### `VerifiableCredential`
W3C Verifiable Credential with Ed25519 proof.

Methods:
- `new(issuer, subject, private_key)` - Create credential
- `verify(did_resolver)` - Verify signature
- `is_expired()` - Check expiration
- `get_claim(key)` - Get claim value

#### `PaymentAuthorization`
Complete authorization chain for payments.

Methods:
- `new(intent, cart, payment)` - Create authorization
- `verify_chain(did_resolver)` - Verify complete chain
- `is_valid()` - Check if still valid

### Error Types

```rust
pub enum Ap2Error {
    InvalidCredential(String),
    SignatureVerificationFailed(String),
    DidResolutionFailed(String),
    MandateValidationFailed(String),
    ConsensusVerificationFailed(String),
    Expired,
    InsufficientAuthorization(String),
    SerializationError(String),
    CryptographicError(String),
}
```

## Standards Compliance

### W3C Verifiable Credentials
- Context: `https://www.w3.org/2018/credentials/v1`
- Proof type: `Ed25519Signature2020`
- Compliant JSON-LD structure

### W3C Decentralized Identifiers (DID)
- DID method: `did:ap2:`
- Verification method support
- Service endpoint definitions
- Controller relationships

### Ed25519 Signatures
- RFC 8032 compliant
- dalek-cryptography implementation
- Deterministic signing

## Future Enhancements

1. **Additional Signature Schemes**
   - ECDSA support
   - BLS signatures for aggregation
   - Post-quantum signatures

2. **Advanced Features**
   - Revocation lists
   - Delegation chains
   - Time-based restrictions
   - Geographic constraints

3. **Integrations**
   - Payment gateway bridges
   - Blockchain anchoring
   - Hardware security module (HSM) support
   - WASM compilation

4. **Performance**
   - Batch verification
   - Signature aggregation
   - Enhanced caching
   - Distributed consensus

## License

MIT OR Apache-2.0

## Contributing

See the main repository CONTRIBUTING.md for guidelines.

## Support

For issues and questions:
- GitHub Issues: https://github.com/agentic-catalog/agentic-payments/issues
- Documentation: https://docs.agentic-catalog.io/ap2