tool.meshservice/README.md

# MeshService

A generic decentralized service layer for mesh networks. Build any peer-to-peer service following the **Announce → Query → Response → Reserve** pattern.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Application Services                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │  FAPP   │  │ Housing │  │ Repair  │  │ Custom  │  ...   │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
│       └────────────┴────────────┴────────────┘              │
│                    Service Layer (this crate)                │
│         ServiceMessage, ServiceRouter, Verification          │
│  ───────────────────────────────────────────────────────    │
│                     Mesh Layer                               │
│    (provided by quicprochat-p2p or other mesh impl)         │
└─────────────────────────────────────────────────────────────┘
```

## Features

- **Generic Protocol**: Any service can be built on top (therapy appointments, housing, repairs, tutoring...)
- **Ed25519 Signatures**: All messages cryptographically signed
- **Verification Framework**: Multi-level trust (self-asserted, peer-endorsed, registry-verified)
- **Efficient Wire Format**: Fixed 64-byte header + CBOR payload
- **Pluggable Handlers**: Register custom services with the router
- **Built-in Services**: FAPP (psychotherapy) and Housing included

## Quick Start

```rust
use meshservice::{
    capabilities,
    identity::ServiceIdentity,
    router::ServiceRouter,
    services::fapp::{FappService, SlotAnnounce, SlotQuery, Specialism, Modality},
};

// Create identity
let identity = ServiceIdentity::generate();

// Create router with FAPP service
let mut router = ServiceRouter::new(capabilities::RELAY);
router.register(Box::new(FappService::relay()));

// Therapist announces slots
let announce = SlotAnnounce::new(
    &[Specialism::CognitiveBehavioral],
    Modality::VideoCall,
    "104",  // Postal prefix
)
.with_slots(3)
.with_profile("https://therapists.de/dr-mueller");

let msg = meshservice::services::fapp::create_announce(&identity, &announce, 1)?;
router.handle(msg, Some(identity.public_key()))?;

// Patient queries
let query = SlotQuery::new(Specialism::CognitiveBehavioral, "104");
let query_msg = meshservice::services::fapp::create_query(&identity, &query)?;
let matches = router.query(&query_msg);

println!("Found {} therapists", matches.len());
```

## Built-in Services

### FAPP (Free Appointment Propagation Protocol)

Decentralized psychotherapy appointment discovery:

| Service ID | Purpose |
|------------|---------|
| `0x0001`   | Therapist slot announcements, patient queries |

```rust
use meshservice::services::fapp::{SlotAnnounce, Specialism, Modality};

let announce = SlotAnnounce::new(
    &[Specialism::TraumaFocused, Specialism::CognitiveBehavioral],
    Modality::InPerson,
    "104",
)
.with_slots(2)
.with_profile("https://kbv.de/123");
```

### Housing

Decentralized room/apartment sharing:

| Service ID | Purpose |
|------------|---------|
| `0x0002`   | Listing announcements, seeker queries |

```rust
use meshservice::services::housing::{ListingAnnounce, ListingType, amenities};

let listing = ListingAnnounce::new(ListingType::Apartment, 65, 850, "104")
    .with_rooms(2)
    .with_amenities(amenities::FURNISHED | amenities::BALCONY);
```

## Verification Framework

Three trust levels:

| Level | Description | Example |
|-------|-------------|---------|
| 0 - None | Bare announcement | Anonymous |
| 1 - Self-Asserted | Profile URL provided | Website link |
| 2 - Peer-Endorsed | Trusted peers vouch | Community rating |
| 3 - Registry-Verified | Official registry | KBV license |

```rust
use meshservice::verification::{Verification, TrustedVerifiers, VerificationLevel};

// Add trusted verifier
let mut verifiers = TrustedVerifiers::new();
verifiers.add(registry_public_key, "KBV Registry", VerificationLevel::RegistryVerified);
router.set_trusted_verifiers(verifiers);

// Require verification for announces
router.set_min_verification_level(2);
```

## Wire Protocol

64-byte fixed header for efficient parsing:

```
 0-3   service_id (u32 LE)
 4     message_type (u8)
 5     version (u8)
 6-7   flags (reserved)
 8-23  message_id (16 bytes)
24-39  sender_address (16 bytes)
40-47  sequence (u64 LE)
48-49  ttl_hours (u16 LE)
50-57  timestamp (u64 LE)
58     hop_count (u8)
59     max_hops (u8)
60-63  payload_len (u32 LE)
---
64+    signature (64 bytes)
128+   payload (CBOR)
...    verifications (optional CBOR)
```

## Building Custom Services

Implement `ServiceHandler`:

```rust
use meshservice::router::{ServiceHandler, ServiceAction, HandlerContext};

struct MyService;

impl ServiceHandler for MyService {
    fn service_id(&self) -> u32 { 0x8001 } // Custom range
    fn name(&self) -> &str { "MyService" }
    
    fn handle(&self, message: &ServiceMessage, ctx: &HandlerContext) 
        -> Result<ServiceAction, ServiceError> 
    {
        match message.message_type {
            MessageType::Announce => Ok(ServiceAction::StoreAndForward),
            MessageType::Query => {
                // Find matches, respond...
                Ok(ServiceAction::Handled)
            }
            _ => Ok(ServiceAction::Drop)
        }
    }
    
    fn matches_query(&self, announce: &StoredMessage, query: &ServiceMessage) -> bool {
        // Custom matching logic
        true
    }
}
```

## Service IDs

| ID | Service |
|----|---------|
| `0x0001` | FAPP (Psychotherapy) |
| `0x0002` | Housing |
| `0x0003` | Repair |
| `0x0004` | Tutoring |
| `0x0005` | Medical |
| `0x0006` | Legal |
| `0x0007` | Volunteer |
| `0x0008` | Events |
| `0x8000+` | Custom/User-defined |

## Examples

```bash
# FAPP demo (therapist + patient)
cargo run --example fapp_service

# Housing demo (landlord + seeker)
cargo run --example housing_service

# Multi-service mesh
cargo run --example multi_service
```

## Testing

```bash
cargo test
```

## License

MIT