h33-client 0.1.0

H33.ai REST API client — async, typed responses, post-quantum attestation verification
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# h33-client

Official Rust client for the [H33](https://h33.ai) post-quantum cryptographic API.

One crate. Full access to FHE encryption, Dilithium signatures, Kyber key exchange, and biometric authentication — all post-quantum secure.

## Install

```toml
[dependencies]
h33-client = "0.1"
```

## Quick Start

```rust
use h33_client::H33Client;

#[tokio::main]
async fn main() -> h33_client::Result<()> {
    let client = H33Client::builder()
        .api_url("https://api.h33.ai")
        .api_key("h33_live_...")
        .build()?;

    // FHE: Encrypt → Compute → Decrypt (data never leaves encrypted form)
    let session = client.fhe_init("bfv").await?;
    let ct = client.fhe_encrypt(&session, "42").await?;
    let result = client.fhe_compute(&session, "add", &[&ct, &ct]).await?;
    let answer = client.fhe_decrypt(&session, &result).await?;
    assert_eq!(answer, "84");

    // Post-quantum signatures (Dilithium)
    let sig = client.sign("important data").await?;
    let valid = client.verify("important data", &sig).await?;
    assert!(valid);

    // Biometric auth (FHE-encrypted, zero exposure)
    let template = vec![0.1; 128]; // 128-dim embedding from your model
    client.biometric_enroll("user_123", &template).await?;
    let matched = client.biometric_verify("user_123", &template).await?;
    assert!(matched);

    Ok(())
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `H33_API_URL` | `http://localhost:8080` | API endpoint |
| `H33_API_KEY` | (required) | Your API key from [h33.ai/pricing](https://h33.ai/pricing) |

```rust
// Auto-configure from environment
let client = H33Client::from_env()?;
```

## API Coverage

| Method | Endpoint | Description |
|--------|----------|-------------|
| `health()` | `GET /health` | Service health check |
| `connect()` | `POST /api/v1/auth/token` | Get JWT (optional, API key works) |
| `fhe_init(scheme)` | `POST /api/v1/fhe/init` | Start FHE session (bfv/ckks) |
| `fhe_encrypt(session, plaintext)` | `POST /api/v1/fhe/encrypt` | Encrypt plaintext |
| `fhe_decrypt(session, ciphertext)` | `POST /api/v1/fhe/decrypt` | Decrypt ciphertext |
| `fhe_compute(session, op, operands)` | `POST /api/v1/fhe/compute` | Homomorphic computation |
| `pq_encrypt(plaintext)` | `POST /api/v1/encrypt` | Kyber + AES-256-GCM encrypt |
| `pq_decrypt(ciphertext)` | `POST /api/v1/decrypt` | Hybrid decrypt |
| `sign(data)` | `POST /api/v1/sign` | Dilithium signature |
| `verify(data, signature)` | `POST /api/v1/verify` | Verify signature |
| `biometric_enroll(user, template)` | `POST /api/v2/biometric/enroll` | Enroll FHE-encrypted template |
| `biometric_verify(user, template)` | `POST /api/v2/biometric/verify` | Verify against enrolled template |
| `usage()` | `GET /api/v1/usage` | Usage statistics |

## Error Handling

All methods return `h33_client::Result<T>`. Errors include HTTP status, error code, message, and optional hint:

```rust
match client.fhe_encrypt(&session, "data").await {
    Ok(ct) => println!("Encrypted: {}", ct),
    Err(H33Error::Api { status, message, hint, .. }) => {
        eprintln!("API error {}: {} ({})", status, message, hint.unwrap_or_default());
    }
    Err(e) => eprintln!("Network error: {}", e),
}
```

## Performance

For latency-critical applications (biometric auth), use [`h33-fhe-client`](https://crates.io/crates/h33-fhe-client) to move BFV encryption client-side, eliminating ~419us from the server pipeline.

## License

MIT