syntax = "proto3"; package chain.v1; import "google/protobuf/empty.proto"; import "chain/v1/common.proto"; // Hub-to-hub federation. A satellite hub opens one persistent // HTTP/2 connection to a primary hub. Within that connection, // the four streams below multiplex. // // Phase 1.0 ships Control + Invoke + Blob + Events. A fifth // stream (`Stream` for bidirectional streaming caps, e.g. live // audio) is reserved for Phase 1.1; the slot stays free in the // service so adding it is purely additive. // // See `docs/architecture/federation.md` for the full design, // security model, and threat-model summary. service Federation { // Long-lived bidirectional Control stream. First two messages // exchanged are always Hello (satellite -> primary) and Accept // (primary -> satellite). Subsequent messages multiplex over // the same channel: advertisements, withdrawals, heartbeats, // renames, and cert renewals. // // Disconnect signals shutdown: the primary withdraws every // capability advertised by this satellite. The satellite is // expected to reconnect with exponential backoff. rpc Control(stream ControlMessage) returns (stream ControlMessage); // Reserved stub. Cross-hub dispatch does NOT use a unary RPC: // the satellite dials outbound (NAT-friendly) and is the gRPC // client, so the primary cannot open a call back into it. Real // dispatch flows over the Control stream via DispatchCall / // DispatchResult (FED-06). This RPC stays declared only so the // service slot is stable; it returns UNIMPLEMENTED. // // The satellite resolves `capability_id` against its **local** // registry; unknown capabilities return CAPABILITY_NOT_SUPPORTED. // The wire never carries executable content — only inputs. rpc Dispatch(DispatchRequest) returns (DispatchResponse); // Bidirectional chunked binary transfer. Used for `bytes` // payloads above `federation.blob_threshold` (default 1 MiB). // The first message on either side is BlobOpen describing the // operation ("upload" or "download"); subsequent messages // carry data or end-of-stream / error markers. rpc Blob(stream BlobChunk) returns (stream BlobChunk); // Server-streaming relay of audit + step events from a // satellite to the primary. The primary's Studio uses this to // show live progress of remote flow runs and to surface // approval-pending notices from remote steps. rpc Events(EventsRequest) returns (stream RelayedEvent); } // ---- Control multiplex ---------------------------------------------- // All Control-stream messages share this envelope so a single // gRPC stream can carry the full state-machine vocabulary // without needing one stream per message kind. message ControlMessage { oneof kind { HelloMessage hello = 1; AcceptMessage accept = 2; AdvertiseMessage advertise = 3; WithdrawMessage withdraw = 4; HeartbeatMessage heartbeat = 5; HeartbeatAck heartbeat_ack = 6; RenameMessage rename = 7; CertRenewRequest cert_renew_request = 8; CertRenewResponse cert_renew_response = 9; // FED-06: cross-hub dispatch multiplexes over this same // satellite-opened stream (the satellite is the gRPC client, // so the primary cannot open a unary call back into it). The // primary sends DispatchCall down; the satellite executes // locally and sends DispatchResult back up, correlated by // request_id. DispatchCall dispatch_call = 10; DispatchResult dispatch_result = 11; } } // Primary -> satellite: please execute this capability call. The // request_id correlates the matching DispatchResult flowing back // up the same Control stream. message DispatchCall { // Per-call correlation id (UUIDv7), primary-generated. Unique // within the connection's in-flight window. string request_id = 1; // The call to execute. Reuses the unary message shape. DispatchRequest request = 2; } // Satellite -> primary: the result of a prior DispatchCall. message DispatchResult { // Echoes the originating DispatchCall.request_id. string request_id = 1; // Outputs / error / timing for the executed call. DispatchResponse response = 2; } // First message a satellite sends after the TLS handshake. The // primary either responds with Accept (success) or closes the // stream with a status carrying a friendlyError-shaped detail // (no overlap on wire_version, bootstrap token rejected, display // name already in use, etc.). message HelloMessage { // Immutable Hub Instance UUID (UUIDv7) generated at the // satellite's first `chain init`. Persisted in `~/.chain/hub-id`. // The federation cert's subject embeds this value; it can // never change without a fresh `chain init`. string hub_id = 1; // Operator-chosen display name (e.g. "satellite-a"). May be // changed later via the Rename message. The primary refuses // a Hello whose display_name collides with another connected // satellite. string display_name = 2; // Ch∆In binary version, informational. Lets the primary record // satellite versions for operator visibility without coupling // them to wire compatibility (which is governed by // wire_versions_supported below). string hub_version = 3; // Set of federation wire-protocol versions the satellite can // speak. The primary picks the highest element also in its own // supported set. Empty list is treated as `[1]`. repeated uint32 wire_versions_supported = 4; // Set of module-WIT contract versions the satellite supports. // Per-capability advertisements carry their own wit_version; // this is the satellite's overall envelope. repeated string wit_versions_supported = 5; // Single-use bootstrap token, present only on the *very first* // connect when the satellite has no federation cert yet. The // primary validates against its issued-but-unused token store, // issues a 24h federation cert in the Accept message, and // marks the token consumed. // // Empty string on every subsequent connect — the satellite // identifies itself with the mTLS cert and this field is // ignored. string bootstrap_token = 6; // Optional region tag the satellite claims at first enrollment. // Signed into the issued cert by the primary; future connects // read region from the cert, not from this field. string region = 7; // PEM-encoded PKCS#10 CSR generated by the satellite on first // enrollment, with its immutable hub UUID in the subject CN. The // primary's CA signs it (pinning that UUID) and returns the leaf // cert in `AcceptMessage.issued_cert_pem`. Empty on reconnects // once the satellite already holds a valid cert. string csr_pem = 8; } // First message the primary sends in response to Hello. Closes // the handshake; the connection is then ready for advertisements // and dispatch. message AcceptMessage { // Wire version both sides will use for the lifetime of this // connection. Highest common element of // `hello.wire_versions_supported` and the primary's own list. uint32 wire_version_chosen = 1; // Primary's own identity, so the satellite can record it in // its routing table and audit log. string primary_hub_id = 2; string primary_display_name = 3; string primary_hub_version = 4; repeated uint32 primary_wire_versions_supported = 5; // Federation cert PEM issued by the primary. Present on // enrollment connect (when hello.bootstrap_token was set) and // on cert renewals (in response to CertRenewRequest). Empty // on plain reconnect with an existing valid cert. string issued_cert_pem = 6; // ISO-8601 expiry of `issued_cert_pem`. Empty when no cert // issued in this message. string cert_expires_at = 7; } // Capability advertisement. Sent after Accept and any time the // satellite's local registry changes (install, uninstall, // disable). Replaces — does not append to — any prior // advertisement from this connection. message AdvertiseMessage { repeated CapabilityAdvertisement capabilities = 1; } // One advertised capability. The primary indexes by // (capability_id, origin_uuid) — never by display name, so a // rename never invalidates the index. message CapabilityAdvertisement { // Fully qualified id, e.g. "text.extract@1.4.2". SemVer // version follows the @. string capability_id = 1; // UUID of the hub that *originally* provides this capability. // Distinct from the connection's sender UUID when an // intermediate hub is re-advertising (mesh phases). string origin_uuid = 2; // Display name of the origin hub at advertisement time. // Operator-friendly label; the primary stores the UUID for // routing and resolves to name for display. string origin_name = 3; // BGP-style path: ordered list of hub UUIDs the advertisement // travelled through, **oldest first**. The receiving hub // refuses to accept an advertisement whose route already // contains its own UUID (loop prevention). repeated string route = 4; // Optional region tag inherited from the origin's cert. // Empty when the origin advertises no region. string region = 5; // Quality metrics measured at the origin hub. Used by the // primary for `auto:healthiest` / `auto:lowest_rtt` selection. Quality quality = 6; // Permission strings the satellite-side module declared, // informational only. Each satellite enforces its own // ceiling locally; the primary cannot widen permissions // remotely. repeated string permissions = 7; // Module WIT contract version. The primary refuses to // dispatch into a satellite advertising a WIT version it does // not support. string wit_version = 8; // Ch∆In binary version that loaded this capability at the // origin. Informational. string hub_version = 9; } // Quality metrics piggybacked on every advertisement update. // Numbers measured at the origin hub; an end-to-end RTT field // (sum across hops) lands in Phase 1.2 when mesh // re-advertisement ships. message Quality { // 50th percentile round-trip time over the recent window. uint32 rtt_p50_ms = 1; // 95th percentile round-trip time over the recent window. uint32 rtt_p95_ms = 2; // Successful invocations / total in last 30 min. 1.0 = all // succeeded. 0.0 = all failed (or no data). float success_rate_30m = 3; // Currently in-flight streams (rough load indicator). uint32 streams_active = 4; // Per-satellite hard limit on concurrent streams. Lets the // primary calculate utilisation for least-loaded selection. uint32 streams_capacity = 5; } // Withdraw one or more capabilities. Equivalent to sending an // Advertise without these entries, but lighter on the wire when // only a small subset changed. message WithdrawMessage { // Fully-qualified ids to withdraw. repeated string capability_ids = 1; // Only advertisements from this origin UUID are affected. string origin_uuid = 2; } // Liveness + RTT probe. Cadence configurable; default 10 s with // jitter. message HeartbeatMessage { // Monotonic per-connection nonce so the Ack can be matched. uint64 nonce = 1; // Milliseconds since epoch on the satellite at send time. int64 satellite_time_ms = 2; } message HeartbeatAck { uint64 nonce = 1; // Milliseconds since epoch on the primary at ack time. int64 primary_time_ms = 2; } // Operator-driven rename. Display name changes do not require a // new cert because the UUID stays the same. The primary // re-validates name uniqueness within its federation, updates // its routing table, and emits an audit event tying old and new // names to the unchanged UUID. message RenameMessage { string new_display_name = 1; } // Cert renewal. The satellite generates a CSR locally, embedding // its immutable hub UUID in the subject. The primary's CA // signing logic MUST verify that the CSR subject's hub UUID // matches the connection's existing mTLS cert UUID — a stolen // cert otherwise lets an attacker renew into a different UUID // and bypass revocation. message CertRenewRequest { // PEM-encoded PKCS#10 certificate signing request. string csr_pem = 1; } message CertRenewResponse { // PEM-encoded fresh cert on success. Empty on refusal. string cert_pem = 1; // ISO-8601 expiry of `cert_pem`. Empty when refused. string expires_at = 2; // Human-readable refusal reason. Empty on success. string error = 3; } // ---- Invoke --------------------------------------------------------- // Dispatch one capability call. The dispatcher at the primary // resolves a flow step's `use:` + `on:` into one DispatchRequest // addressed at the chosen satellite's UUID. message DispatchRequest { // Fully qualified capability id (matching the advertised id). string capability_id = 1; // UUID of the hub expected to execute. The recipient verifies // that this matches its own UUID OR (Phase 1.2+ mesh) routes // the call along the next hop toward the target UUID. Required. string target_hub_id = 2; // Inputs in the same Payload shape Hub::Submit uses, so // module-side conversion is identical to local invocation. map inputs = 3; // UUIDv7 correlation id shared across hops + audit logs on // both sides for a single cross-hub call. Lets `chain admin // events` reconstruct the full trace later. string trace_id = 4; // Per-call nonce; the satellite rejects replays within a // sliding window (default 60 s) to defend against captured- // call replay attacks. string nonce = 5; // Operator-friendly caller identity (e.g. token name, user // login) for the satellite's local audit attribution. Empty // for anonymous primary configurations. string caller_name = 6; // Optional region requirement. When set, the satellite must // refuse the call if its own region tag doesn't match // (case-insensitive exact match in 1.0; hierarchical match // lands in 1.1). string region_required = 7; } message DispatchResponse { // Outputs on success. map outputs = 1; // Error shape on failure. The `code` mirrors common.ChainError // codes; the satellite maps its local ChainError to this wire. ChainError error = 2; // Wall-clock duration of the actual module invocation at the // satellite, in milliseconds. Excludes federation transport. uint32 duration_ms = 3; // UUID of the hub that actually executed. Same as // `target_hub_id` in 1.0; in Phase 1.2+ relayed calls may // surface a different value when an intermediate hub had a // local copy. string executed_at_hub_id = 4; } // ---- Blob ------------------------------------------------------------ // One chunk on the bidirectional Blob stream. The opening // message describes the operation; subsequent messages carry // payload bytes or end-of-stream / error markers. // // Chunk-size convention: 256 KiB. Receivers MUST NOT assume a // fixed chunk size — HTTP/2 framing and senders may differ. message BlobChunk { oneof kind { BlobOpen open = 1; bytes data = 2; BlobEof eof = 3; BlobError error = 4; } } message BlobOpen { // "upload" or "download". Other values reserved for future // expansion (e.g. "resume", "verify"). string operation = 1; // Sha256 (lowercase hex) when known up-front. Required for // downloads (which sha256 to fetch); empty for streaming // uploads where the sha is computed during the transfer. string sha256 = 2; // Total payload size in bytes when known up-front; 0 means // "streaming with unknown size". uint64 size_bytes = 3; // Mime type metadata propagated from the source `Bytes` payload. string mime_type = 4; // HMAC-signed blob reference URL for downloads. The primary // verifies signature, expiry, and audience (target hub UUID) // before honouring the open. Empty on uploads. string signed_ref = 5; } message BlobEof { // Final sha256 of the assembled blob. The receiver verifies // this against its running hash; a mismatch closes the stream // with a BlobError and discards the partial. string sha256 = 1; // Final byte count actually transferred. Lets the receiver // sanity-check against any prior `BlobOpen.size_bytes`. uint64 size_bytes = 2; } message BlobError { // Stable kebab-cased code so callers can map to friendlyError // copy. Known values: "size-cap-exceeded", "hash-mismatch", // "expired", "audience-mismatch", "permission-denied", // "internal". string code = 1; // Free-form diagnostic text. string message = 2; } // ---- Events relay --------------------------------------------------- // Subscription request from a primary that wants to receive // remote-step events. The satellite first replays up to // `backfill` historical events then streams live ones. message EventsRequest { // Optional filter on the origin hub UUID. Empty = receive // everything the satellite relays. string filter_hub_id = 1; // Optional glob-style filter on event_type strings. // E.g. ["step.*", "approval.*"]. Empty = no filter. repeated string event_types = 2; // Backfill count before switching to live tail. Defaults to // 50 when 0; capped at 1000 by the satellite. uint32 backfill = 3; } // One forwarded event. The event payload mirrors LoggedEvent's // shape so existing Studio renderers handle it without // branching. The origin annotation lets Studio show "from // satellite X" badges. message RelayedEvent { // UUID of the hub the event originated at. string origin_hub_id = 1; // Display name of the origin hub at relay time. May be stale // (operator just renamed) — receivers resolve UUID -> name // from their routing table as the source of truth. string origin_display_name = 2; // Event payload. Shape mirrors hub.proto's LoggedEvent so // Studio doesn't need a second renderer; the fields listed // here are the wire stable subset. string event_id = 3; string timestamp = 4; string event_type = 5; string flow_execution = 6; string invocation_id = 7; string flow_name = 8; string step_id = 9; string module_name = 10; string module_version = 11; int64 duration_ms = 12; string error = 13; // Free-form JSON. Capped at the satellite's // `federation.limits.event_detail_max_bytes` (default 32 KiB) // before forwarding to defend against exfiltration via large // detail blobs. string detail = 14; string caller_name = 15; }