Overview

Contract cloud-v0 for the hosted-Native control plane and the tenant data-plane proxy.

Hyphae Cloud control plane 0.0.1

Hyphae Cloud runs one Hyphae Native process per project and fronts it with authentication, routing, and limits. This document covers two surfaces served by the same daemon (cloudd):

/v0/* — the control plane: accounts, projects, keys, lifecycle. Authenticated with a session token from /v0/signup or /v0/login.
/v2/* — the tenant data plane. Every request is forwarded verbatim to the project’s own hyphae serve loopback listener. Authenticated with a project key (hyp1_...) from POST /v0/projects/{id}/keys. The key alone selects the project. A request may additionally name a project through Host: <project>.<suffix> (default suffix localtest.me, label prj_<16 hex> or the bare 16 hex) or the X-Hyphae-Project header; a name is honoured only if the key belongs to that project, otherwise 403 authorization_denied. Path-based references (/p/{id}/v2) are not part of cloud-v0. The wire contract behind /v2/* is Native’s contracts/openapi/hyphae-v2.yaml, pinned at Native 3.0.0. This document does not restate it and does not widen it.

Snapshots are verified Native backups of a sleeping tenant; restore replaces the data directory (it is not a branch). head is a live probe when running and Native’s offline status when asleep.

Storage (/v0/projects/{id}/storage/*) keeps object bytes in the Cloud’s blob backend (a local directory, or S3-compatible MinIO) and the catalog in the Cloud control store. Native is not the blob authority. Upload and download URLs are Cloud routes used with the session bearer, never presigned blob-store URLs. Session-owner only; project keys cannot use storage in this phase.

Realtime (/v0/projects/{id}/realtime/*) is an ephemeral in-process fanout over Server-Sent Events: not Native, not durable, not a WAL.

Edge Functions v0 (/v0/projects/{id}/functions/*) run trusted project code as a separate, time-boxed, bounded process on the daemon host. Not a sandbox against a hostile tenant; see docs/product/claims.md.

Two credentials: the owner’s hyc0_ session (every route) and a live hyp1_ project key (data plane only: /v2/*, storage objects and bucket list, realtime, function invoke). Each operation lists what it accepts.

/healthz and /readyz are unauthenticated probes for a supervisor or load balancer. They never name projects or carry secrets.

The daemon speaks plain HTTP on loopback; TLS is terminated by a front (Caddy, nginx) in front of it. See docs/operate.md.

Information

OpenAPI version: 3.1.0

Authentication

sessionToken

Opaque session token from /v0/signup or /v0/login. Control plane only. Rejected after expires_at (default 24 h); log in again.

Security scheme type: http

Bearer format: hyc0_<64-lowercase-hex>

projectKey

Live project key from POST /v0/projects/{id}/keys. Authorizes the project data plane — /v2/*, storage objects, realtime, function invoke — and no owner-only route (those answer 401). Verified and revocation-checked on every request; never forwarded to Native or injected into functions.