Skip to content

PhyCloud

PhyCloud is the trusted-data backplane of PhyWare — an append-only, cryptographically verifiable provenance store for autonomous-systems telemetry. Every event ingested by PhyCloud is sequenced, hashed with SHA-256 over a canonical JSON encoding, and linked into a tamper-evident chain that downstream consumers (the phyware CLI, PhyComp, the admin dashboard, custom audit tooling) can verify offline.

Canonical implementation

The canonical PhyCloud service is the Rust implementation under PhyCloud/rust/:

  • axum + tokio HTTP server, tower-http middleware.
  • sqlx async database layer (SQLite for dev, PostgreSQL for production) with embedded sqlx::migrate!() schema migrations.
  • argon2 password hashing, jsonwebtoken for JWT, tracing-subscriber for structured JSON logs.
  • Single static binary, small container image, no Python runtime.

The historical Python MVP was removed in #269, one release cycle after the #218 cutover. Operators who still need to migrate should follow the operator migration guide.

Quick start

The repo-root docker-compose.yml now builds the canonical phycloud service from the Rust Dockerfile:

# Bring up Postgres + the canonical Rust PhyCloud service.
docker compose up -d phycloud

# Health check
curl -sf http://localhost:8000/health

For local development without Docker:

source SetEnv.sh
cd PhyCloud/rust
PHYCLOUD_AUTO_MIGRATE=true cargo run --release

Feature surface

Area Endpoints Notes
Health & readiness GET /health, GET /health/ready
Bootstrap POST /bootstrap, GET /bootstrap/status First-run super-admin key issuance
Events POST /api/v1/events, POST /api/v1/events/batch, GET /api/v1/events, GET /api/v1/events/{id} Append-only, hash-chained
Sources GET /api/v1/sources, GET /api/v1/sources/{id}/latest, GET /api/v1/fleet/status Fleet rollups (collapses the 4N+1 dashboard round-trip)
Authentication POST /auth/login, POST /api/v1/auth/password/*, POST /api/v1/auth/sessions/* JWT, API keys, password (argon2id), sessions
OAuth 2.0 POST /oauth/token, POST /oauth/introspect Federated PhyComp integration
Admin (tenants, keys, licenses) POST/GET/DELETE /api/v1/admin/{tenants,keys,licenses} Super-admin gated
Users POST/GET /api/v1/users/{invite,accept-invite,me,…} Invite-based onboarding
Evidence lockers POST/GET /api/v1/lockers*, POST /api/v1/verify Cryptographic evidence escrow
License validation POST /api/v1/admin/licenses/validate PhyTrace SDK license check

A full OpenAPI document is served at GET /openapi.json (and a Swagger UI at GET /docs) by the Rust service.

Provenance model

Each ingested event is tagged with:

  • ingested_at — server timestamp.
  • sequence_number — strictly monotonic ordering key.
  • content_hash — SHA-256 of canonical-JSON-encoded event payload.
  • previous_hash — the prior event's content_hash, forming a tamper-evident chain.
  • source_verified — validation status assigned by the ingest pipeline.

The Rust service emits bit-identical hashes to the legacy Python MVP for the same input — verified by replay-style compatibility tests in PhyCloud/rust/tests/provenance_compat.rs.

Architecture

flowchart LR
    A[PhyTrace SDK] -->|UDM events| B[PhyCloud — Rust]
    C[phyware CLI] -->|query / admin| B
    D[PhyComp] -->|fetch + introspect| B
    E[Admin dashboard] -->|browse + manage| B
    B -->|persist| F[(PostgreSQL / SQLite)]

Further reading