ProvnZero Proxy#

The Rust-based proxy for the ProvnZero project. Built with Axum, it accepts HPKE-sealed prompts, decrypts them transiently for provider submission, and avoids persisting prompt contents to disk or logs.

Features#

• RFC 9180 HPKE: Standard-compliant Hybrid Public Key Encryption (X25519-HKDF-SHA256-AES256GCM).
• Axum: Async HTTP routing.
• Rate Limiting: Request throttling via tower-governor.
• Graceful Shutdown: Parity and memory zeroization on SIGINT/SIGTERM.
• Signed Receipts: Ed25519-signed JSON receipts for request metadata.
• Verified Streaming: Per-chunk sealed stream envelopes plus a signed terminal proof over the rolling chunk hash-chain.
• Structured Chat Compatibility: Prompt shorthand, system messages, multi-turn chat, and tool/function-call payloads survive the sealed sync round-trip.
• Built-In Demo Mode: Local echo provider when upstream keys are not configured.

Security Architecture#

ProvnZero is designed for zero-persistence operation with minimized plaintext lifetime.

• Ephemeral Context: Every request uses an HPKE-sealed exchange against a short-lived server key.
• Self-Pruning Memory: Expired ephemeral keys are automatically pruned.
• No Prompt Persistence: Zero database dependency and no prompt logging.
• Structured Sync Path: Sync responses are re-sealed as JSON so assistant messages, finish reasons, and tool calls survive end-to-end.
• Streaming Note: The stream path seals each returned chunk and signs the final proof. The SDK can pin one or more expected attestation keys.
• Protocol Ownership Note: The current signed receipt, rolling stream hash, and final-proof JSON payloads are ProvnZero-local contracts today.

Getting Started#

Prerequisites#

• Rust 1.75+
• (Optional) WSL for Linux-parity testing

Run Locally#

# Clone the repository
cd provnzero-proxy

# Build for release
cargo build --release

# Run with environment variables
OPENAI_API_KEY=sk-xxxx cargo run

If no upstream provider key is present, the proxy starts with a built-in demo provider so local SDK smoke tests can still run.

Deployment (Railway)#

ProvnZero is pre-configured for Railway deployment:

railway up

API Specification#

1. Initialize Session#

POST /v1/init

Begins an HPKE session. Response:

{
  "pubkey": "base64-X25519-server-public-key",
  "key_id": "unique-session-id"
}

2. Submit Encrypted Completion#

POST /v1/completions

Submits an HPKE-sealed prompt or chat payload for processing. Request:

{
  "key_id": "unique-session-id",
  "encapsulated_key": "base64-hpke-encap-key",
  "ciphertext": "base64-hpke-ciphertext",
  "provider": "openai"
}

Configuration#

Operational endpoints:

• GET /health: liveness probe
• GET /ready: readiness probe with provider and mTLS state
• GET /metrics: Prometheus-style runtime counters

License#

Apache 2.0