A service in front of a hub needs four things: start a flow, follow it, read what a detached run produced, and decide approvals. This is that surface, plus the part a gateway cannot test without: a fake hub that speaks the same service from the same .proto files and can be scripted into every failure a real hub produces. Errors carry the hub's own class (chain-error-kind), a coarse family, and reachedHub, which separates a refused connection from a hub that reports a dependency as down. Both arrive as gRPC UNAVAILABLE, and a gateway that shows 'service not reachable' for the second one lies to its users. The .proto files are carried verbatim and loaded at runtime, so no generated code can drift from the contract; two guards hold the copies in place, and a skew suite runs the same client against a real hub binary. 32 hermetic tests plus 4 against a real hub. Signed-off-by: Dr. Stefan Flemming <sf@flemming.it>
1756 lines
66 KiB
Protocol Buffer
1756 lines
66 KiB
Protocol Buffer
syntax = "proto3";
|
|
|
|
package chain.v1;
|
|
|
|
import "google/protobuf/empty.proto";
|
|
import "chain/v1/common.proto";
|
|
|
|
// The Hub service is what CLI clients, web UIs, or other tools talk to.
|
|
service Hub {
|
|
// Submit a flow for execution.
|
|
rpc Submit(SubmitRequest) returns (SubmitResponse);
|
|
|
|
// Submit a flow and follow its execution live (added 1.1). Same
|
|
// request as unary Submit; the response is a stream of step markers,
|
|
// ephemeral module events (host.emit-event), and finally the result
|
|
// or an error. Works over native gRPC and gRPC-Web (server
|
|
// streaming). Unary Submit is unchanged for clients that don't care.
|
|
rpc SubmitStream(SubmitRequest) returns (stream SubmitStreamEvent);
|
|
|
|
// List modules known to this hub.
|
|
rpc ListModules(google.protobuf.Empty) returns (ModuleList);
|
|
|
|
// Detached-invocation lifecycle (added 1.1). Only invocations
|
|
// submitted with detach=true are tracked; results are retained under
|
|
// hard operator limits (size/count/TTL) and NOT persisted across a
|
|
// hub restart.
|
|
rpc GetInvocationStatus(InvocationId) returns (InvocationStatus);
|
|
rpc GetInvocationResult(InvocationId) returns (SubmitResponse);
|
|
rpc CancelInvocation(InvocationId) returns (CancelInvocationResponse);
|
|
|
|
// List every tracked detached invocation (newest-first) for a
|
|
// monitor surface — Studio's detached-runs list. Returns an empty
|
|
// list (not an error) when detached invocations are disabled.
|
|
rpc ListInvocations(google.protobuf.Empty) returns (InvocationList);
|
|
|
|
// Liveness / readiness probe.
|
|
rpc Health(google.protobuf.Empty) returns (HealthStatus);
|
|
}
|
|
|
|
// HubAdmin exposes administrative operations on the hub: inspect
|
|
// installed modules, query the event log, manage saved flows.
|
|
//
|
|
// Calls to HubAdmin from external clients are unauthenticated in
|
|
// Phase 0/0.5 (localhost trust). Phase 1+ adds bearer-token / mTLS
|
|
// auth on this surface. Calls from within modules require the
|
|
// `hub:` permission scope (read / install / admin).
|
|
service HubAdmin {
|
|
// List capabilities provided by all installed modules.
|
|
rpc ListCapabilities(google.protobuf.Empty) returns (CapabilityList);
|
|
|
|
// Return full manifest data for one installed module.
|
|
rpc ModuleInfo(ModuleInfoRequest) returns (ModuleInfoResponse);
|
|
|
|
// Check whether a module is allowed a given permission under the
|
|
// operator's policy. Returns the decision plus the reason.
|
|
rpc CheckPermission(CheckPermissionRequest) returns (CheckPermissionResponse);
|
|
|
|
// Read a slice of the event log, newest first.
|
|
rpc EventLog(EventLogRequest) returns (EventLogResponse);
|
|
|
|
// Server-streaming variant of EventLog. The hub first emits up
|
|
// to `limit` historical events (newest-last so clients receive
|
|
// them in chronological order), then keeps the stream open and
|
|
// forwards every freshly-appended event in real time. Reads
|
|
// require the Read scope when auth is on.
|
|
rpc StreamEvents(StreamEventsRequest) returns (stream LoggedEvent);
|
|
|
|
// Saved-flow management. A saved flow is a YAML file under
|
|
// <data_dir>/flows/<name>.yaml; it can be re-run by name later.
|
|
rpc SaveFlow(SaveFlowRequest) returns (SaveFlowResponse);
|
|
rpc DeleteFlow(DeleteFlowRequest) returns (DeleteFlowResponse);
|
|
rpc ListFlows(google.protobuf.Empty) returns (FlowList);
|
|
rpc RunSavedFlow(RunSavedFlowRequest) returns (SubmitResponse);
|
|
|
|
// Return the parsed structure of a saved flow (declared
|
|
// inputs + their type tags) so a client can render an
|
|
// input form before calling RunSavedFlow.
|
|
rpc GetFlowDefinition(GetFlowDefinitionRequest) returns (FlowDefinition);
|
|
|
|
// List the shared hub's project registry (`general` first) —
|
|
// the lightweight labels that group flows, runs, approvals and
|
|
// audit events. Only `open` and `protected` projects appear:
|
|
// sealed projects are their own hub instance and are never
|
|
// known to a shared hub (docs/architecture/projects.md).
|
|
// Studio's workspace switcher reads this list.
|
|
rpc ListProjects(google.protobuf.Empty) returns (ProjectList);
|
|
|
|
// Search the bundled (and Phase 1+: federated) store index for
|
|
// modules matching a query.
|
|
rpc SearchStore(SearchStoreRequest) returns (StoreSearchResponse);
|
|
|
|
// List the configured module stores (operator config `stores:`)
|
|
// plus the implicit bundled seed, for the Studio store manager.
|
|
rpc ListStores(ListStoresRequest) returns (ListStoresResponse);
|
|
|
|
// Register a new module store and merge its index into the live
|
|
// store so its modules become searchable + installable immediately.
|
|
rpc AddStore(AddStoreRequest) returns (AddStoreResponse);
|
|
|
|
// Drop a configured store by name and rebuild the live index
|
|
// without it. The bundled seed cannot be removed.
|
|
rpc RemoveStore(RemoveStoreRequest) returns (RemoveStoreResponse);
|
|
|
|
// Install a module from a .chain bundle (local path or http(s) URL).
|
|
rpc InstallModule(InstallModuleRequest) returns (InstallModuleResponse);
|
|
|
|
// Same install, with live progress. Emits an update per phase and,
|
|
// during the download, as bytes arrive; the last message carries
|
|
// either the finished response or the error. Clients that only need
|
|
// the outcome keep using the unary InstallModule above — this exists
|
|
// so a waiting operator can see that a slow download is progressing
|
|
// rather than hung.
|
|
rpc InstallModuleStream(InstallModuleRequest)
|
|
returns (stream InstallProgressEvent);
|
|
|
|
// Remove an installed module by name. Wipes the module
|
|
// directory and re-scans the registry; writes a
|
|
// `module.uninstalled` audit event. Surfaced by the Studio
|
|
// module sheet's "Uninstall" affordance.
|
|
rpc UninstallModule(UninstallModuleRequest) returns (UninstallModuleResponse);
|
|
|
|
// Fetch a module's README (or other docs) and return the
|
|
// markdown content as a string. The hub knows how to
|
|
// authenticate against the configured registry — Studio
|
|
// doesn't need to handle credentials. Studio's Store detail
|
|
// sheet renders the result inline.
|
|
rpc FetchModuleDocs(FetchModuleDocsRequest) returns (FetchModuleDocsResponse);
|
|
|
|
// Read the inline-docs (MODULE.md / MODULE.<locale>.md) of an
|
|
// installed module from disk. No network fetch, no provider-
|
|
// specific URL probing — the docs ship in the .chain bundle and
|
|
// live next to module.wasm on disk after install. Returns an
|
|
// empty body when the module is installed but ships no inline
|
|
// docs; Studio uses that to hide the docs button entirely.
|
|
rpc GetInstalledModuleDocs(GetInstalledModuleDocsRequest) returns (GetInstalledModuleDocsResponse);
|
|
|
|
// Invoke an installed Studio plugin's `theme` hook. Returns
|
|
// the plugin's proposed Material 3 ColorScheme for the
|
|
// brightness the caller asked for ("light" or "dark"). The
|
|
// first end-to-end RPC of the Studio-plugin subsystem; the
|
|
// `translate` and `output-view` hooks get their own RPCs as
|
|
// the matching Studio surfaces ship.
|
|
rpc InvokePluginTheme(InvokePluginThemeRequest) returns (InvokePluginThemeResponse);
|
|
|
|
// Invoke an installed Studio plugin's `translate` hook.
|
|
// The first user surface that consumes this is Studio's
|
|
// FaiEnBadge — when an operator has a translate plugin
|
|
// installed, server-supplied English text (MCP tool
|
|
// descriptions, n8n endpoint names) gets translated
|
|
// on-the-fly into the active locale instead of carrying
|
|
// the honest-but-rough [EN] badge.
|
|
rpc InvokePluginTranslate(InvokePluginTranslateRequest) returns (InvokePluginTranslateResponse);
|
|
|
|
// List system.approval@^0 entries, optionally filtered by status.
|
|
rpc ListApprovals(ListApprovalsRequest) returns (ApprovalList);
|
|
|
|
// Reviewer decision on a pending approval. `decision` selects
|
|
// approve / reject; `reviewer` and `reason` supply the audit
|
|
// attribution. The flow that posted the approval resumes (or
|
|
// fails) on the next polling tick.
|
|
rpc DecideApproval(DecideApprovalRequest) returns (DecideApprovalResponse);
|
|
|
|
// Walk the event-log hash chain and return whether tampering
|
|
// was detected. Surfaced by the CLI as `chain admin verify-events`
|
|
// and by Studio's health page.
|
|
rpc VerifyEventChain(google.protobuf.Empty) returns (VerifyEventChainResponse);
|
|
|
|
// Wipe every audit event and seed the log with a single
|
|
// `chain.reset` marker. Refused on `beta` / `production` for
|
|
// compliance — only callable on `local` / `dev`. Surfaced by
|
|
// the CLI as `chain admin events clear`.
|
|
rpc ClearEventLog(ClearEventLogRequest) returns (ClearEventLogResponse);
|
|
|
|
// Read the operator's `default_scope:` (the ordered list of
|
|
// provider segments the bare-form capability resolver tries
|
|
// when a flow names a capability without `<provider>/`
|
|
// prefix). Always returns the current in-memory copy.
|
|
rpc GetDefaultScope(google.protobuf.Empty) returns (DefaultScopeResponse);
|
|
|
|
// Replace the operator's `default_scope:`. The hub validates
|
|
// each entry against the namespace catalog before writing to
|
|
// disk. Returns the resulting snapshot so the client can
|
|
// refresh its UI in one round-trip.
|
|
rpc SetDefaultScope(SetDefaultScopeRequest) returns (DefaultScopeResponse);
|
|
|
|
// Re-read `auth.tokens:` from operator config + env vars and
|
|
// atomically swap the live token store. Used by operators to
|
|
// rotate tokens without restarting the daemon. Returns the
|
|
// new token count. Errors if the new config is invalid (env
|
|
// var missing, duplicate secret, no scopes, …) — the
|
|
// existing store stays in place so a botched rotation can't
|
|
// lock the operator out.
|
|
rpc ReloadAuth(google.protobuf.Empty) returns (ReloadAuthResponse);
|
|
|
|
// Read-only snapshot of the authentication policy as persisted
|
|
// in the operator config, for operator surfaces (Studio
|
|
// Settings → Security). Never carries secret material: token
|
|
// entries expose the env-var NAME and whether that variable is
|
|
// currently set — never the value; the jwt-rs256 validator
|
|
// exposes its key SOURCE (inline / file path), never the key.
|
|
// Admin-scoped like ReloadAuth.
|
|
rpc AuthStatus(google.protobuf.Empty) returns (AuthStatusResponse);
|
|
|
|
// Assemble the guided-setup plan for the given answers — a pure
|
|
// computation (chain_core::guided_setup::assemble), no state
|
|
// change, nothing written. Lets a GUI render the setup preview
|
|
// over its existing hub connection instead of spawning the CLI:
|
|
// on macOS that subprocess can be the app's first file-system
|
|
// touch and trigger a permission prompt BEFORE the operator has
|
|
// seen what would be set up — the wrong order for trust. Apply
|
|
// remains a deliberate separate step.
|
|
rpc PlanSetup(PlanSetupRequest) returns (PlanSetupResponse);
|
|
|
|
// List host services declared in the operator config. Each
|
|
// entry carries name + endpoint; reachability is operator-side
|
|
// (on-demand `chain service status` or Studio probe).
|
|
rpc ListServices(google.protobuf.Empty) returns (ServiceList);
|
|
|
|
// Declare a new host service in the operator config. Fails with
|
|
// ALREADY_EXISTS when a service of that name is configured.
|
|
rpc DeclareService(DeclareServiceRequest) returns (DeclareServiceResponse);
|
|
|
|
// Compare the running hub's version against the channel release
|
|
// manifest. Surfaced by the CLI as `chain update check` and by
|
|
// Studio's Doctor page as a "v0.x.y available" pill. Network
|
|
// failures are returned as `manifest_reachable=false` rather
|
|
// than gRPC errors so Studio can render gracefully when the
|
|
// release host is unreachable (air-gapped, offline laptop).
|
|
rpc CheckUpdate(google.protobuf.Empty) returns (CheckUpdateResponse);
|
|
|
|
// Active channel + per-channel daemon status. Lets Studio's
|
|
// settings page render which channel is current and whether
|
|
// each daemon is up. Mirrors the CLI's `fai daemon status`.
|
|
rpc ChannelStatus(google.protobuf.Empty) returns (ChannelStatusResponse);
|
|
|
|
// Filesystem locations the daemon owns: log file, db file,
|
|
// modules dir, flows dir, config file. Studio's Doctor page
|
|
// surfaces these so operators on Windows (who never touch
|
|
// a shell) can open them via the OS file manager.
|
|
rpc DaemonPaths(google.protobuf.Empty) returns (DaemonPathsResponse);
|
|
|
|
// Configured MCP servers + their last-discovery report.
|
|
// Studio's MCP-clients editor renders the result. Mirrors
|
|
// `chain mcp list` on the CLI.
|
|
rpc ListMcpClients(google.protobuf.Empty) returns (ListMcpClientsResponse);
|
|
|
|
// Re-run discovery against every configured MCP server and
|
|
// update the *live* store-index in place. Synthetic entries
|
|
// for tools the server no longer exposes are dropped.
|
|
// Mirrors `chain mcp refresh` but operates on the running
|
|
// daemon — Studio doesn't need to ask the operator to
|
|
// restart anything.
|
|
rpc RefreshMcpClients(google.protobuf.Empty) returns (ListMcpClientsResponse);
|
|
|
|
// Persist a new MCP server in `~/.chain/config.yaml` and
|
|
// re-run discovery. Returns the resulting list (same shape
|
|
// as ListMcpClients) so Studio can repaint in one round-trip.
|
|
rpc AddMcpClient(McpClientConfigEntry) returns (ListMcpClientsResponse);
|
|
|
|
// Remove an MCP server by name and re-run discovery so its
|
|
// synthetic capabilities disappear from the store.
|
|
rpc RemoveMcpClient(RemoveMcpClientRequest) returns (ListMcpClientsResponse);
|
|
|
|
// n8n bridges. Same shape as the MCP client RPCs above —
|
|
// every active workflow surfaces as `n8n.<name>.<slug>`.
|
|
rpc ListN8nEndpoints(google.protobuf.Empty) returns (ListN8nEndpointsResponse);
|
|
rpc RefreshN8nEndpoints(google.protobuf.Empty) returns (ListN8nEndpointsResponse);
|
|
rpc AddN8nEndpoint(N8nEndpointConfigEntry) returns (ListN8nEndpointsResponse);
|
|
rpc RemoveN8nEndpoint(RemoveN8nEndpointRequest) returns (ListN8nEndpointsResponse);
|
|
|
|
// Read-only system-AI status. Lets Studio render the
|
|
// "configure in Settings" affordance when the feature is
|
|
// off, and the privacy-mode badge when it is on.
|
|
rpc SystemAiStatus(google.protobuf.Empty) returns (SystemAiStatusResponse);
|
|
|
|
// Ask the system AI a one-shot question. Errors carry the
|
|
// failure category (disabled / env-missing / http / parse)
|
|
// so Studio can map them to the inline-fix-hint copy from
|
|
// `docs/architecture/system-ai.md`.
|
|
rpc AskAi(AskAiRequest) returns (AskAiResponse);
|
|
|
|
// Persist a new system-AI configuration. Updates the live
|
|
// hub state AND writes back to ~/.chain/config.yaml so the
|
|
// change survives daemon restart. Used by Studio's settings
|
|
// editor. Returns the resulting status (same shape as
|
|
// SystemAiStatus) so the UI can refresh in one round-trip.
|
|
rpc UpdateSystemAi(UpdateSystemAiRequest) returns (SystemAiStatusResponse);
|
|
|
|
// Probe a system-AI configuration with a tiny ping. The
|
|
// request body carries the *draft* config the operator is
|
|
// editing — Test Connection works *before* Save so the user
|
|
// doesn't have to commit a broken config to validate it.
|
|
// An all-empty body falls back to the live in-memory config.
|
|
rpc TestSystemAi(TestSystemAiRequest) returns (AskAiResponse);
|
|
|
|
// List the models the configured provider exposes via
|
|
// `GET /v1/models`. Studio's editor populates the model
|
|
// dropdown from this. Same draft-vs-live semantics as
|
|
// TestSystemAi.
|
|
rpc ListSystemAiModels(TestSystemAiRequest) returns (ListSystemAiModelsResponse);
|
|
|
|
// Pull (download + install) an Ollama model via the native
|
|
// /api/pull endpoint. Synchronous, may take minutes for
|
|
// large models. Same error-kind taxonomy as AskAi.
|
|
rpc PullSystemAiModel(PullSystemAiModelRequest) returns (PullSystemAiModelResponse);
|
|
|
|
// Same pull, with live progress. A model pull moves gigabytes, so
|
|
// the unary form above leaves a person waiting minutes with nothing
|
|
// to look at. Emits Ollama's own status plus byte counts per layer,
|
|
// ending in the response.
|
|
rpc PullSystemAiModelStream(PullSystemAiModelRequest)
|
|
returns (stream PullProgressEvent);
|
|
|
|
// Drop every cached System-AI explanation. Surfaced in
|
|
// Studio's Settings so operators can force a clean slate
|
|
// without changing model/privacy mode (which also flushes).
|
|
rpc ClearSystemLlmCache(google.protobuf.Empty) returns (ClearSystemLlmCacheResponse);
|
|
|
|
// Drop a single cached entry by prompt — the same prompt
|
|
// Studio sent in AskAi. Used by the "Regenerate" button so
|
|
// the next AskAi call falls through to the live provider.
|
|
rpc ForgetCachedExplanation(AskAiRequest) returns (google.protobuf.Empty);
|
|
|
|
// Detected host hardware tier + summary line. Studio's
|
|
// System-AI editor uses this to mark models as "may be slow
|
|
// on your hardware" without requiring a benchmark.
|
|
rpc HardwareInfo(google.protobuf.Empty) returns (HardwareInfoResponse);
|
|
|
|
// Bundled curated model database (quality tier, parameter
|
|
// count, recommended-for tier, notes). Studio merges this
|
|
// with the live `/v1/models` listing for richer chips. The
|
|
// `last_reviewed` field tells the operator how stale the
|
|
// curation is.
|
|
rpc ListSystemAiCuratedModels(google.protobuf.Empty)
|
|
returns (ListSystemAiCuratedModelsResponse);
|
|
|
|
// Federation (primary side). Issue a single-use bootstrap
|
|
// token enrolling a named satellite (`chain admin satellites
|
|
// peer-add`), and list the satellites currently connected
|
|
// (`chain admin satellites list`).
|
|
rpc IssueBootstrapToken(IssueBootstrapTokenRequest)
|
|
returns (IssueBootstrapTokenResponse);
|
|
rpc ListSatellites(google.protobuf.Empty) returns (SatelliteList);
|
|
// Revoke a satellite by UUID (`chain admin satellites revoke`):
|
|
// drops any live connection and refuses future connects even
|
|
// with a still-valid cert. Persisted across restarts.
|
|
rpc RevokeSatellite(RevokeSatelliteRequest) returns (google.protobuf.Empty);
|
|
}
|
|
|
|
message RevokeSatelliteRequest {
|
|
// Immutable hub UUID of the satellite to revoke.
|
|
string hub_id = 1;
|
|
}
|
|
|
|
message SubmitRequest {
|
|
// The flow definition as raw YAML.
|
|
bytes flow_yaml = 1;
|
|
// Named input values for the flow.
|
|
map<string, Payload> inputs = 2;
|
|
// When true (added 1.1), Submit returns immediately with the
|
|
// invocation id and the flow keeps running in the background. Poll
|
|
// GetInvocationStatus / fetch GetInvocationResult, or follow it live
|
|
// via SubmitStream. Only detached invocations are retained; unary
|
|
// detach=false is unchanged (synchronous, stateless).
|
|
bool detach = 3;
|
|
// Project slug this run belongs to (added phase 2). Overrides the
|
|
// flow YAML's `project:`; empty → the flow's project, then
|
|
// `general`. Every audit event, approval and detached row from this
|
|
// run is stamped (and hashed) with it. Grouping/filtering only —
|
|
// not tenancy.
|
|
string project = 4;
|
|
// Caller's key for "this is the same request as before" (added
|
|
// in hub 0.25). A second submit carrying a key the hub has already seen
|
|
// returns the first run instead of starting a second one, which is
|
|
// what a payment webhook that retries needs. At most 128 printable
|
|
// ASCII characters; empty means no deduplication. Scoped to the
|
|
// project.
|
|
string idempotency_key = 5;
|
|
}
|
|
|
|
message SubmitResponse {
|
|
InvocationId invocation_id = 1;
|
|
// Named output values produced by the flow.
|
|
map<string, Payload> outputs = 2;
|
|
}
|
|
|
|
// One event in a SubmitStream (added 1.1). Exactly one field is set.
|
|
message SubmitStreamEvent {
|
|
oneof event {
|
|
StepStarted step_started = 1;
|
|
StepFinished step_finished = 2;
|
|
ModuleEvent module_event = 3;
|
|
// Terminal success — identical to the unary SubmitResponse.
|
|
SubmitResponse final_result = 4;
|
|
// Terminal failure — the flow (or a step) errored.
|
|
StreamError error = 5;
|
|
}
|
|
}
|
|
|
|
message StepStarted {
|
|
string step = 1;
|
|
// Capability the step resolved to, e.g. "text.extract".
|
|
string capability = 2;
|
|
}
|
|
|
|
message StepFinished {
|
|
string step = 1;
|
|
bool ok = 2;
|
|
int64 duration_ms = 3;
|
|
}
|
|
|
|
// An ephemeral event a module emitted via host.emit-event (WIT 1.1).
|
|
// Never written to the audit log.
|
|
message ModuleEvent {
|
|
// The step whose module emitted this.
|
|
string step = 1;
|
|
// Module-defined label, e.g. "progress" / "token".
|
|
string name = 2;
|
|
// Event body.
|
|
Payload payload = 3;
|
|
}
|
|
|
|
message StreamError {
|
|
string message = 1;
|
|
// Machine-readable error class, the same vocabulary as the
|
|
// `chain-error-kind` trailer of a unary error (added in hub 0.25):
|
|
// flow_rejected, step_failed, step_timeout, approval_rejected,
|
|
// approval_timeout, unavailable, overloaded, precondition,
|
|
// not_found, conflict, internal. Empty from a hub older than 0.25.
|
|
string kind = 2;
|
|
}
|
|
|
|
// Lifecycle of a detached invocation (added 1.1).
|
|
message InvocationStatus {
|
|
enum Phase {
|
|
PHASE_UNKNOWN = 0;
|
|
PENDING = 1;
|
|
RUNNING = 2;
|
|
SUCCEEDED = 3;
|
|
FAILED = 4;
|
|
CANCELLED = 5;
|
|
}
|
|
Phase phase = 1;
|
|
// Step currently executing (RUNNING), empty otherwise.
|
|
string current_step = 2;
|
|
// RFC 3339 timestamps; finished_at empty until the flow ends.
|
|
string started_at = 3;
|
|
string finished_at = 4;
|
|
// Error message when phase == FAILED, empty otherwise.
|
|
string error = 5;
|
|
}
|
|
|
|
message CancelInvocationResponse {
|
|
// True if a running invocation was signalled to cancel; false if it
|
|
// was already finished or unknown.
|
|
bool cancelled = 1;
|
|
}
|
|
|
|
// One row in the detached-runs monitor list.
|
|
message InvocationEntry {
|
|
string invocation_id = 1;
|
|
InvocationStatus status = 2;
|
|
// Flow name this invocation is running, empty when unknown.
|
|
string flow_name = 3;
|
|
// Project slug the run was stamped with (`general` when none).
|
|
string project = 4;
|
|
}
|
|
|
|
message InvocationList {
|
|
// Tracked detached invocations, newest-first by start time.
|
|
repeated InvocationEntry invocations = 1;
|
|
// Whether the operator enabled detached invocations
|
|
// (`detached.enabled`). Lets monitor UIs distinguish "feature
|
|
// off" from "on, but no runs yet" instead of guessing (added
|
|
// additively; absent = false on pre-1.1 hubs).
|
|
bool detached_enabled = 2;
|
|
}
|
|
|
|
message ModuleList {
|
|
repeated ModuleSummary modules = 1;
|
|
}
|
|
|
|
message ModuleSummary {
|
|
string name = 1;
|
|
string version = 2;
|
|
repeated CapabilityRef provides = 3;
|
|
}
|
|
|
|
message HealthStatus {
|
|
enum State {
|
|
UNKNOWN = 0;
|
|
SERVING = 1;
|
|
NOT_SERVING = 2;
|
|
}
|
|
State state = 1;
|
|
string detail = 2;
|
|
}
|
|
|
|
// HubAdmin messages
|
|
|
|
message CapabilityList {
|
|
repeated CapabilityEntry capabilities = 1;
|
|
}
|
|
|
|
message CapabilityEntry {
|
|
// Full capability identifier, e.g. "text.extract".
|
|
string capability = 1;
|
|
// Capability version (semver).
|
|
string version = 2;
|
|
// Module providing this capability.
|
|
string module_name = 3;
|
|
// Module's own version.
|
|
string module_version = 4;
|
|
// Where this capability comes from. Studio gates install
|
|
// affordances on this — only "wasm" caps have a bundle to
|
|
// install. Empty string is treated as "wasm" for
|
|
// backwards-compat with older hubs.
|
|
// "wasm" — declared by an installed WASM module
|
|
// "builtin" — implemented in the hub itself
|
|
// (e.g. system.approval)
|
|
// "federated" — discovered from an external MCP/n8n server;
|
|
// not installable via the module-store path
|
|
string kind = 5;
|
|
// Publisher identity (provider segment) of the capability.
|
|
// Always set on registered capabilities. "fai" for legacy
|
|
// bundles that didn't declare a provider. For federated
|
|
// capabilities, this is the operator's service `name:`
|
|
// (e.g. "deepwiki", "bmds.spark"). Wire-level addition for
|
|
// the naming convention; see
|
|
// `docs/reference/capability-namespaces.yaml`.
|
|
string provider = 6;
|
|
// Transport that delivers this capability to the Hub.
|
|
// Distinct from `kind` (which captures the install-vs-builtin
|
|
// distinction) — `source_kind` records HOW the Hub reaches
|
|
// the implementation. Studio renders this as a badge next to
|
|
// the capability name.
|
|
// "bundle" — installed .chain WASM bundle
|
|
// "system" — Hub built-in (fai.system/*)
|
|
// "mcp" — federated via an MCP service
|
|
// "n8n" — federated via an n8n endpoint
|
|
// "temporal" — federated via a Temporal service (e.g. SPARK)
|
|
// "webhook" — reserved for Phase 1+
|
|
string source_kind = 7;
|
|
// Whether the version on this capability is advisory rather
|
|
// than a hard contract. True for federated capabilities whose
|
|
// upstream service does not honour semver; operator pins are
|
|
// labels, not guarantees. Studio renders a warning badge.
|
|
bool version_advisory = 8;
|
|
}
|
|
|
|
message ModuleInfoRequest {
|
|
string module_name = 1;
|
|
}
|
|
|
|
message ModuleInfoResponse {
|
|
string name = 1;
|
|
string version = 2;
|
|
repeated CapabilityRef provides = 3;
|
|
// Permission strings exactly as declared in module.yaml.
|
|
repeated string permissions = 4;
|
|
// Filesystem location the module was loaded from.
|
|
string directory = 5;
|
|
// MIME allow-list for bytes-shaped inputs, copied verbatim
|
|
// from `module.yaml`'s `accepts_mime:` field. Empty means
|
|
// "no declared restriction". Studio uses this to pre-filter
|
|
// the OS file-picker so operators don't pick a file the
|
|
// module would reject.
|
|
repeated string accepts_mime = 6;
|
|
// Capabilities this module advisorily expects to be available,
|
|
// copied from module.yaml's optional `consumes:` list. Empty
|
|
// means "this is a leaf module with no declared dependencies".
|
|
// Studio surfaces "you'll also want these installed" hints
|
|
// based on this list; the hub does NOT enforce.
|
|
repeated ConsumedCapability consumes = 7;
|
|
// Declared inputs the module's invoke function accepts. The
|
|
// editor uses this to render per-field input ports with their
|
|
// canonical names + types and i18n tooltips. Empty when the
|
|
// manifest declares no inputs (rare; usually means the module
|
|
// is a pure data source).
|
|
repeated ModuleField inputs = 8;
|
|
// Declared outputs the module produces. The editor uses this
|
|
// to render one output port per declared field instead of
|
|
// collapsing every downstream reference into a single anchor.
|
|
repeated ModuleField outputs = 9;
|
|
}
|
|
|
|
message ConsumedCapability {
|
|
// Capability name, e.g. "llm.chat".
|
|
string capability = 1;
|
|
// Semver range constraint, e.g. "^0". Empty = any version.
|
|
string version = 2;
|
|
// Free-form rationale from the manifest's `why:` field.
|
|
string why = 3;
|
|
}
|
|
|
|
// One declared input or output field on a module. Carries the
|
|
// type descriptor (text / json / bytes / file) and a locale →
|
|
// description map for tooltips. The map is keyed by IETF locale
|
|
// tag ("en", "de", "ja", …) so callers pick their active
|
|
// locale with a single lookup + "en" fallback.
|
|
message ModuleField {
|
|
// Field name, e.g. "prompt" or "model_endpoint".
|
|
string name = 1;
|
|
// Type descriptor: one of text / json / bytes / file.
|
|
string type = 2;
|
|
// Locale → description. Empty map = no description declared
|
|
// (schema_version 1/2 manifests, or v3 manifests that left
|
|
// the field in shorthand form).
|
|
map<string, string> description = 3;
|
|
}
|
|
|
|
message CheckPermissionRequest {
|
|
string module_name = 1;
|
|
// Permission string in `<scope>: <value>` form.
|
|
string permission = 2;
|
|
}
|
|
|
|
message CheckPermissionResponse {
|
|
bool allowed = 1;
|
|
// Human-readable reason. Empty when allowed.
|
|
string reason = 2;
|
|
}
|
|
|
|
message EventLogRequest {
|
|
// Maximum number of events to return. Defaults to 100 when 0.
|
|
int32 limit = 1;
|
|
// Optional event_type filter; when empty, all types are returned.
|
|
repeated string event_types = 2;
|
|
// Optional project filter (slug). Empty = all projects. Scopes
|
|
// the audit view to one project — the per-project compliance
|
|
// export use case (`chain admin events --project`).
|
|
string project = 3;
|
|
}
|
|
|
|
message EventLogResponse {
|
|
repeated LoggedEvent events = 1;
|
|
}
|
|
|
|
message StreamEventsRequest {
|
|
// Backfill size before the stream switches to live updates.
|
|
// 0 means "no backfill, only new events". Defaults to 50 when
|
|
// unset; capped at 1000 server-side to bound the initial buffer.
|
|
int32 backfill = 1;
|
|
// Optional event_type filter; when empty, all types are streamed.
|
|
// The filter applies to both the backfill prefix and the live
|
|
// tail.
|
|
repeated string event_types = 2;
|
|
// Optional project filter (slug). Empty = all projects. Applies
|
|
// to both the backfill prefix and the live tail.
|
|
string project = 3;
|
|
}
|
|
|
|
message LoggedEvent {
|
|
string event_id = 1;
|
|
string timestamp = 2;
|
|
string event_type = 3;
|
|
string flow_execution = 4;
|
|
string invocation_id = 5;
|
|
string flow_name = 6;
|
|
string step_id = 7;
|
|
string module_name = 8;
|
|
string module_version = 9;
|
|
int64 duration_ms = 10;
|
|
string error = 11;
|
|
// Free-form JSON-string carrying event-type-specific fields:
|
|
// input/output sizes, model digest, sha256, etc. Empty when
|
|
// the event type has no structured detail. Studio renders
|
|
// this as a code block in the audit drill-down.
|
|
string detail = 12;
|
|
// Operator-friendly name of the token whose holder
|
|
// triggered this event. Empty when the call was anonymous
|
|
// (auth.tokens: not configured), when the event was emitted
|
|
// by hub-internal code (boot housekeeping, federation
|
|
// discovery), or when the row pre-dates the audit-
|
|
// attribution migration (0006).
|
|
string caller_name = 13;
|
|
// Project slug the run was stamped with (`general` when the
|
|
// run carried no explicit project). Bound into the V4 audit
|
|
// hash, so the attribution is tamper-evident. Empty on rows
|
|
// pre-dating the project migration (0008).
|
|
string project = 14;
|
|
}
|
|
|
|
message SaveFlowRequest {
|
|
// Flow name (used as the file name with .yaml extension).
|
|
string name = 1;
|
|
// Flow YAML content.
|
|
bytes flow_yaml = 2;
|
|
// If false and a flow with this name exists, return AlreadyExists.
|
|
bool overwrite = 3;
|
|
}
|
|
|
|
message SaveFlowResponse {
|
|
string name = 1;
|
|
bool created = 2;
|
|
}
|
|
|
|
message DeleteFlowRequest {
|
|
string name = 1;
|
|
}
|
|
|
|
message DeleteFlowResponse {
|
|
string name = 1;
|
|
}
|
|
|
|
message FlowList {
|
|
repeated FlowSummary flows = 1;
|
|
}
|
|
|
|
message FlowSummary {
|
|
string name = 1;
|
|
// Path on disk relative to the saved-flows directory.
|
|
string path = 2;
|
|
// Bytes on disk.
|
|
int64 size_bytes = 3;
|
|
// Verbatim `use:` strings of every step in the flow,
|
|
// deduplicated and sorted. Lets a GUI client decide whether
|
|
// a flow is currently runnable (every entry resolves to an
|
|
// installed module) without parsing the YAML itself.
|
|
repeated string required_capabilities = 4;
|
|
// The flow's own top-level `project:` slug; empty when the
|
|
// YAML has none (a run then lands in the caller's project,
|
|
// then `general`). The file wins on mismatch — same semantics
|
|
// as the CLI (docs/architecture/projects.md).
|
|
string project = 5;
|
|
// True when the file still carries the bundled-sample header —
|
|
// it arrived via the hub's sample import, not from an operator.
|
|
// Clients mark and group these so examples are never mistaken
|
|
// for real work. Deleting the header claims the flow.
|
|
bool sample = 6;
|
|
}
|
|
|
|
// One registered project (shared-hub registry row). Sealed
|
|
// projects never appear here — they are their own hub instance.
|
|
message ProjectInfo {
|
|
// Stable lowercase-kebab identifier stamped onto every run.
|
|
string slug = 1;
|
|
// Human display name (renamable without touching history).
|
|
string name = 2;
|
|
// Accent colour (hex, e.g. "#8b7cf6") for UI marking. Empty
|
|
// when unset.
|
|
string color = 3;
|
|
// Free-form description. Empty when unset.
|
|
string description = 4;
|
|
// Protection level: "open" (pure label) or "protected"
|
|
// (logically separated — no hard process barrier; the honest
|
|
// wording every UI must keep).
|
|
string isolation = 5;
|
|
// ISO-8601 UTC creation timestamp.
|
|
string created_at = 6;
|
|
}
|
|
|
|
message ProjectList {
|
|
// All registered projects, `general` first, then by display
|
|
// name (case-insensitive).
|
|
repeated ProjectInfo projects = 1;
|
|
}
|
|
|
|
message RunSavedFlowRequest {
|
|
string name = 1;
|
|
map<string, Payload> inputs = 2;
|
|
// Project slug override (added phase 2); empty → the saved flow's
|
|
// own `project:`, then `general`.
|
|
string project = 3;
|
|
}
|
|
|
|
message GetFlowDefinitionRequest {
|
|
string name = 1;
|
|
}
|
|
|
|
// Parsed shape of a saved flow. Currently surfaces only the
|
|
// declared inputs — that is what Studio needs to render its
|
|
// run-flow form. Fields can grow (steps, outputs) without
|
|
// breaking older clients.
|
|
message FlowDefinition {
|
|
string name = 1;
|
|
// Declared input keys plus their declared type tag, exactly
|
|
// as the flow YAML's `inputs:` section spelled them. Common
|
|
// values: "text", "bytes", "json", "file".
|
|
repeated FlowInputSpec inputs = 2;
|
|
}
|
|
|
|
message FlowInputSpec {
|
|
// Input key (the name the flow YAML uses).
|
|
string name = 1;
|
|
// Declared type tag from the flow YAML — opaque string so
|
|
// the wire stays stable as the type system grows.
|
|
string type = 2;
|
|
}
|
|
|
|
message SearchStoreRequest {
|
|
// Free-text search; matches name, tagline, description, category, tags.
|
|
string query = 1;
|
|
// Optional category filter.
|
|
string category = 2;
|
|
// Optional tag filter.
|
|
string tag = 3;
|
|
// Optional status filter: "published", "alpha", or "planned".
|
|
string status = 4;
|
|
// Maximum results; defaults to 50 when 0.
|
|
int32 limit = 5;
|
|
// Exact-match provider segment filter (0.12+). Empty string
|
|
// matches any provider.
|
|
string provider = 6;
|
|
// First-dotted-segment-of-name filter (0.12+). E.g. "text"
|
|
// matches text.extract, text.summarize, … but not
|
|
// image.classify. Empty matches any namespace.
|
|
string namespace = 7;
|
|
}
|
|
|
|
message StoreSearchResponse {
|
|
repeated StoreEntry entries = 1;
|
|
}
|
|
|
|
message InstallModuleRequest {
|
|
// Local path or http(s) URL of the .chain bundle, OR a
|
|
// capability name (e.g. "text.extract") resolved via the
|
|
// store index.
|
|
string source = 1;
|
|
// Optional expected SHA-256 hex string for verification.
|
|
string expected_sha256 = 2;
|
|
// Optional explicit version when `source` is a capability
|
|
// name. Ignored for URL / local-path sources (the bundle's
|
|
// own manifest dictates the version). Empty string falls
|
|
// back to "highest-priority version from the store index".
|
|
string version = 3;
|
|
}
|
|
|
|
message InstallModuleResponse {
|
|
string name = 1;
|
|
string version = 2;
|
|
// Number of capabilities the installed module provides.
|
|
int32 capability_count = 3;
|
|
}
|
|
|
|
// One message in an InstallModuleStream.
|
|
message InstallProgressEvent {
|
|
oneof event {
|
|
// Progress moved, or a phase started or finished.
|
|
InstallProgressUpdate update = 1;
|
|
// The install succeeded; always the final message.
|
|
InstallModuleResponse finished = 2;
|
|
// The install failed; always the final message. Carries the same
|
|
// text the unary call would have returned as its status message.
|
|
string failed = 3;
|
|
}
|
|
}
|
|
|
|
// A single progress observation.
|
|
message InstallProgressUpdate {
|
|
// Stable phase identifier: "resolve", "download" or "install".
|
|
// Clients map it to their own wording; it is not display text.
|
|
string phase = 1;
|
|
// English fallback label for the phase ("Downloading"). Clients with
|
|
// their own translations key off `phase` and ignore this.
|
|
string stage = 2;
|
|
// Overall progress across all phases, 0..100, monotonic. Absent
|
|
// means the extent is not knowable yet — show an indeterminate
|
|
// indicator, never a bar parked at zero.
|
|
optional float percent = 3;
|
|
// Bytes received so far during the download phase.
|
|
uint64 bytes_received = 4;
|
|
// Total bytes the server announced. Zero means the server sent no
|
|
// content-length, so only `bytes_received` is meaningful.
|
|
uint64 bytes_total = 5;
|
|
// The named phase just finished.
|
|
bool phase_done = 6;
|
|
}
|
|
|
|
message UninstallModuleRequest {
|
|
// Module name as the registry knows it. Empty → InvalidArgument.
|
|
string name = 1;
|
|
// Optional exact version to remove when multiple versions of the
|
|
// same `(provider, name)` are installed side-by-side. Empty
|
|
// falls back to "remove the highest-version match".
|
|
string version = 2;
|
|
}
|
|
|
|
message UninstallModuleResponse {
|
|
string name = 1;
|
|
// Version that was removed; "unknown" when the manifest was
|
|
// unreadable for some reason but the directory still got wiped.
|
|
string version = 2;
|
|
}
|
|
|
|
message FetchModuleDocsRequest {
|
|
// Module name as the store-index knows it. The hub looks up
|
|
// its repository URL and tries the well-known raw-README
|
|
// paths (Forgejo / GitHub / GitLab style), then any
|
|
// `docs_url` override the module declares.
|
|
string name = 1;
|
|
// Preferred locale code (e.g. "de", "en"). When set, the hub
|
|
// first tries `README.<locale>.md` before falling back to the
|
|
// generic `README.md`. Empty string = no locale preference.
|
|
string locale = 2;
|
|
}
|
|
|
|
message FetchModuleDocsResponse {
|
|
// Empty on success; otherwise one of:
|
|
// "not_found" — module not in the store-index
|
|
// "no_docs" — index has no repository or docs URL
|
|
// "network" — http error / unreachable
|
|
// "auth" — registry returned 401/403
|
|
// "parse" — body was not utf-8
|
|
string error_kind = 1;
|
|
// Human-readable detail. On success this is the markdown
|
|
// content; on failure a fix hint.
|
|
string text = 2;
|
|
// The URL the hub fetched from, so Studio can render a
|
|
// "View on <host>" link for context.
|
|
string source_url = 3;
|
|
}
|
|
|
|
message GetInstalledModuleDocsRequest {
|
|
// Capability id (e.g. `text.extract`) or module-manifest name
|
|
// (e.g. `text-extract`). The hub maps capability → module via
|
|
// the registry; falls back to treating the name as a
|
|
// directory name.
|
|
string name = 1;
|
|
// Preferred locale code (e.g. "de", "en"). When set and not
|
|
// "en", `MODULE.<locale>.md` is tried first; otherwise the
|
|
// generic `MODULE.md` is used. Empty string = no preference.
|
|
string locale = 2;
|
|
}
|
|
|
|
message GetInstalledModuleDocsResponse {
|
|
// Markdown body. Empty when the module is installed but ships
|
|
// no inline docs — Studio uses this to hide its docs button.
|
|
string text = 1;
|
|
// Absolute path on the hub host that the body was read from,
|
|
// for "loaded from /path/MODULE.md" hints in Studio. Empty
|
|
// when text is empty.
|
|
string source_path = 2;
|
|
// True when the module wasn't installed at all. Distinct from
|
|
// "installed but no inline docs" so Studio can show different
|
|
// affordances ("install first" vs "no inline docs available").
|
|
bool not_installed = 3;
|
|
}
|
|
|
|
message InvokePluginThemeRequest {
|
|
// Capability name the operator asked for, e.g.
|
|
// `studio.theme.solarized`. The hub maps this to the
|
|
// installed plugin directory.
|
|
string capability = 1;
|
|
// "light" or "dark" — the plugin returns a ColorScheme
|
|
// for this brightness. Plugins that don't recognise the
|
|
// value return PluginError::declined and the hub
|
|
// surfaces that as a friendly error.
|
|
string brightness = 2;
|
|
}
|
|
|
|
message InvokePluginTranslateRequest {
|
|
// Capability name (e.g. `studio.translate.ollama`).
|
|
string capability = 1;
|
|
// Text to translate. UTF-8, arbitrary length the plugin
|
|
// tolerates.
|
|
string text = 2;
|
|
// BCP-47 source locale. Empty = let the plugin auto-detect.
|
|
string from_locale = 3;
|
|
// BCP-47 target locale. Required; the host always knows it.
|
|
string to_locale = 4;
|
|
}
|
|
|
|
message InvokePluginTranslateResponse {
|
|
// Translated text. Returns verbatim what the plugin
|
|
// emits — no normalisation by the hub.
|
|
string translated = 1;
|
|
}
|
|
|
|
message InvokePluginThemeResponse {
|
|
// Echo of the brightness input. Plugins are expected to
|
|
// round-trip it; if they don't the client treats that as
|
|
// a contract violation.
|
|
string brightness = 1;
|
|
// 14 ARGB tokens in Material 3 order:
|
|
// primary, on_primary, secondary, on_secondary,
|
|
// tertiary, on_tertiary, error, on_error,
|
|
// surface, on_surface, surface_variant,
|
|
// on_surface_variant, outline, outline_variant.
|
|
// Studio merges any missing slot (well-behaved plugins
|
|
// send all 14) with its built-in fallback before
|
|
// applying the scheme.
|
|
repeated uint32 tokens = 2;
|
|
}
|
|
|
|
message ListApprovalsRequest {
|
|
// Filter by status. Empty = all. Allowed wire values:
|
|
// "pending", "approved", "rejected", "expired".
|
|
repeated string statuses = 1;
|
|
// Maximum rows; defaults to 100 when 0.
|
|
int32 limit = 2;
|
|
// Optional project filter (slug). Empty = all projects.
|
|
string project = 3;
|
|
}
|
|
|
|
message ApprovalList {
|
|
repeated PendingApprovalEntry entries = 1;
|
|
}
|
|
|
|
message PendingApprovalEntry {
|
|
string approval_id = 1;
|
|
string flow_execution = 2;
|
|
string flow_name = 3;
|
|
string step_id = 4;
|
|
string prompt = 5;
|
|
// Truncated string preview of the payload the flow handed to
|
|
// the approval step, for reviewer context.
|
|
string payload_preview = 6;
|
|
string created_at = 7;
|
|
// Empty when the approval has no timeout.
|
|
string expires_at = 8;
|
|
// One of "pending", "approved", "rejected", "expired".
|
|
string status = 9;
|
|
// Empty until decided.
|
|
string decided_at = 10;
|
|
string decided_by = 11;
|
|
string reason = 12;
|
|
// Project slug the requesting run was stamped with
|
|
// (`general` when the run carried no explicit project).
|
|
string project = 13;
|
|
}
|
|
|
|
message DecideApprovalRequest {
|
|
string approval_id = 1;
|
|
enum Decision {
|
|
DECISION_UNSPECIFIED = 0;
|
|
APPROVE = 1;
|
|
REJECT = 2;
|
|
}
|
|
Decision decision = 2;
|
|
// Reviewer attribution, recorded in the audit trail. Required.
|
|
string reviewer = 3;
|
|
// Free-form reason. Required for REJECT, ignored for APPROVE.
|
|
string reason = 4;
|
|
}
|
|
|
|
message DecideApprovalResponse {
|
|
string approval_id = 1;
|
|
// The new status: "approved" or "rejected".
|
|
string status = 2;
|
|
}
|
|
|
|
message VerifyEventChainResponse {
|
|
// Total events scanned.
|
|
int64 total = 1;
|
|
// Number of events verified before any tamper detection.
|
|
// Equal to total on a clean chain.
|
|
int64 verified = 2;
|
|
// Empty when no tampering was detected; otherwise the
|
|
// event_id of the first inconsistent row.
|
|
string tampered_at = 3;
|
|
}
|
|
|
|
message ServiceList {
|
|
repeated DeclaredService services = 1;
|
|
}
|
|
|
|
// Declare a host service in the operator config (`services:`).
|
|
// The hub persists it to ~/.chain/config.yaml with the same
|
|
// round-trip semantics as the MCP/n8n writers (every other key
|
|
// stays intact). Services are read at daemon start, so the
|
|
// response says honestly that a restart is required.
|
|
message DeclareServiceRequest {
|
|
string name = 1;
|
|
string endpoint = 2;
|
|
// Empty defaults to "/".
|
|
string health_path = 3;
|
|
repeated string tags = 4;
|
|
}
|
|
|
|
message DeclareServiceResponse {
|
|
// True until the hub learns to hot-reload `services:` — the
|
|
// caller should surface "takes effect after a daemon restart".
|
|
bool restart_required = 1;
|
|
}
|
|
|
|
message DeclaredService {
|
|
string name = 1;
|
|
string endpoint = 2;
|
|
// Empty defaults to "/".
|
|
string health_path = 3;
|
|
repeated string tags = 4;
|
|
// Network reach of `endpoint`, classified from its host part
|
|
// (no DNS lookups — named hosts other than localhost report
|
|
// "unknown"):
|
|
// "loopback" — 127.0.0.0/8, ::1, localhost
|
|
// "private" — RFC1918 / ULA / link-local ranges
|
|
// "public" — any other literal IP
|
|
// "unknown" — unparseable, or a hostname we cannot judge
|
|
// Empty from pre-0.23 hubs.
|
|
string exposure = 5;
|
|
}
|
|
|
|
message StoreEntry {
|
|
string name = 1;
|
|
string tagline_en = 2;
|
|
string tagline_de = 3;
|
|
string description_en = 4;
|
|
string description_de = 5;
|
|
string category = 6;
|
|
repeated string tags = 7;
|
|
repeated string requires_capabilities = 8;
|
|
repeated string requires_services = 9;
|
|
string license = 10;
|
|
string repository = 11;
|
|
string best_version = 12;
|
|
// Status of best_version: "published", "alpha", "planned", or empty.
|
|
string status = 13;
|
|
bool installed = 14;
|
|
// True iff the store-index marks this module as editorially
|
|
// featured. Studio renders featured entries in a separate
|
|
// strip above the main grid. Curated quarterly in the hub's
|
|
// bundled seed.yaml — same review cadence as the curated
|
|
// model database.
|
|
bool featured = 15;
|
|
// Optional URL of a square icon (PNG / SVG, 256px+).
|
|
// Studio loads and renders this in the detail sheet's hero
|
|
// header in place of the category-derived fallback. Empty
|
|
// → fall back to the category icon.
|
|
string icon_url = 16;
|
|
// Optional screenshot URLs in display order. Studio renders
|
|
// them as a horizontally-scrollable strip in the detail
|
|
// sheet so operators can see what the module *does* before
|
|
// installing.
|
|
repeated string screenshot_urls = 17;
|
|
// Explicit docs URL override. Empty → hub falls back to the
|
|
// well-known raw-README paths against `repository`.
|
|
// Use this when the README lives at a non-default branch /
|
|
// path or when the docs are a separate Markdown file.
|
|
string docs_url = 18;
|
|
// Origin of this entry. "native" (downloadable bundle, the
|
|
// default for every seed.yaml entry) or "federated" (routes
|
|
// through a bridge — MCP, n8n, …). Studio uses the value to
|
|
// branch the install action.
|
|
string kind = 19;
|
|
// Provider id for federated entries. Empty for native.
|
|
// For MCP this is the operator's `mcp_clients[].name`.
|
|
// Studio renders "via mcp:<provider>" so the operator sees
|
|
// where a synthetic capability comes from.
|
|
string provider = 20;
|
|
// Transport delivering this entry's capability. Distinct
|
|
// from `kind` (native-vs-federated) — `source_kind` says
|
|
// HOW the Hub reaches the implementation. Values mirror
|
|
// `CapabilityEntry.source_kind`:
|
|
// "bundle" — installed .chain WASM bundle (native entries)
|
|
// "mcp" — federated via an MCP service
|
|
// "n8n" — federated via an n8n endpoint
|
|
// "temporal" — federated via a Temporal service (e.g. SPARK)
|
|
// "webhook" — reserved for Phase 1+
|
|
// Empty string falls back to deriving from `kind` for
|
|
// pre-0.12 hubs.
|
|
string source_kind = 21;
|
|
// Name of the store this entry was loaded from: "bundled" for the
|
|
// built-in seed, otherwise the operator-added store's name. Distinct
|
|
// from source_kind (the transport) — this is the ORIGIN store. Studio
|
|
// groups modules by it and shows a "from <store>" label.
|
|
string source = 22;
|
|
// Canonical, normalized category slug (e.g. "data", "text-language",
|
|
// "studio-themes"). The hub maps the free-form `category` onto a
|
|
// fixed taxonomy by capability namespace, so different stores using
|
|
// different labels ("data" vs "data-processing") land in ONE bucket.
|
|
// Studio groups + filters by this, not the raw `category`. Empty
|
|
// from pre-0.21 hubs → Studio falls back to `category`.
|
|
string canonical_category = 23;
|
|
// Human-readable label for `canonical_category` (e.g. "Data &
|
|
// Formats"). English; Studio may localize via the slug.
|
|
string canonical_category_label = 24;
|
|
// How an install of this entry would be verified, given its
|
|
// origin store and the operator's CURRENT security policy. The
|
|
// hub computes this with the same resolution the install path
|
|
// enforces (pinned store key -> trusted publishers -> policy),
|
|
// so the display can never disagree with the gate:
|
|
// "pinned-key" — verified against the origin store's
|
|
// pinned cosign key (or the built-in
|
|
// official key for bundled/official)
|
|
// "trusted-publishers" — verified against the applicable
|
|
// trusted-publisher list
|
|
// "unverified" — require_signatures is off; installs
|
|
// are NOT signature-checked
|
|
// "blocked" — policy requires signatures but no key
|
|
// material applies to this source; an
|
|
// install would be refused
|
|
// "federated" — bridge entry (MCP/n8n/…); no bundle
|
|
// signature applies
|
|
// Empty from pre-0.23 hubs — clients keep their generic note.
|
|
string install_verification = 25;
|
|
// Maintainer display strings from the store index (one per
|
|
// person/organization). Empty when the index does not specify
|
|
// any — clients render an honest "not specified".
|
|
repeated string maintainers = 26;
|
|
// Where the module's data comes from, for `source.*` capabilities.
|
|
// Absent for every other module: a text splitter reaches no
|
|
// third-party material and has no provenance to declare.
|
|
optional DataSource data_source = 27;
|
|
}
|
|
|
|
// Provenance of the material a `source.*` module fetches.
|
|
//
|
|
// Separate from the module's own licence, which covers its code. A
|
|
// module can be Apache-2.0 while the corpus it reaches is
|
|
// public-domain statute, CC-BY, or licence-gated. Clients show this
|
|
// before the install button so an operator sees the terms they are
|
|
// taking on.
|
|
message DataSource {
|
|
// Publisher, as a person would name it.
|
|
string name = 1;
|
|
// Canonical URL of the upstream source.
|
|
string url = 2;
|
|
// Terms in plain words, not SPDX: the material often carries no
|
|
// software licence at all.
|
|
string license = 3;
|
|
// Attribution the operator must carry with the output. Empty when
|
|
// the upstream requires none.
|
|
string attribution = 4;
|
|
// True when a copy of the data ships inside the module bundle.
|
|
// Forbidden for `source.*` modules, allowed elsewhere only when
|
|
// `redistribution` says the publisher permits it, so a client can
|
|
// show the operator which of the two they are installing.
|
|
bool bundled = 5;
|
|
// What the publisher's terms say about passing the data on:
|
|
// `allowed`, `forbidden`, `unclear`, or empty when the question
|
|
// does not arise (nothing is bundled).
|
|
string redistribution = 6;
|
|
}
|
|
|
|
message ChannelStatusResponse {
|
|
// Active channel pointer from `~/.chain/current-channel`.
|
|
string active = 1;
|
|
repeated ChannelEntry channels = 2;
|
|
}
|
|
|
|
message ChannelEntry {
|
|
string name = 1;
|
|
uint32 port = 2;
|
|
// True iff a daemon is currently bound to that channel's port
|
|
// (PID file present + process alive).
|
|
bool running = 3;
|
|
// Endpoint string from `~/.chain/run/<channel>.endpoint` when
|
|
// the daemon is up, otherwise empty.
|
|
string endpoint = 4;
|
|
}
|
|
|
|
message DaemonPathsResponse {
|
|
// Channel-scoped log file path (empty if Studio cannot
|
|
// resolve one — e.g. older daemon writes only to stderr).
|
|
string log_path = 1;
|
|
// SQLite audit-log database path.
|
|
string db_path = 2;
|
|
// Modules directory the registry scans.
|
|
string modules_dir = 3;
|
|
// Saved flows directory.
|
|
string flows_dir = 4;
|
|
// Operator config file (~/.chain/config.yaml).
|
|
string config_path = 5;
|
|
// PID file the daemon supervisor writes (for the active
|
|
// channel).
|
|
string pid_path = 6;
|
|
}
|
|
|
|
message CheckUpdateResponse {
|
|
// The active channel ("dev", "beta", "production").
|
|
string channel = 1;
|
|
// The version the running hub was built with.
|
|
string local_version = 2;
|
|
// The version the manifest advertises as latest. Empty if
|
|
// `manifest_reachable` is false.
|
|
string latest_version = 3;
|
|
// True iff `latest_version > local_version` (semver-aware).
|
|
bool update_available = 4;
|
|
// RFC 3339 timestamp of the release. Empty if not present.
|
|
string released_at = 5;
|
|
// URL of the release notes for `latest_version`. Empty if not
|
|
// present in the manifest.
|
|
string release_notes_url = 6;
|
|
// True iff the release host responded with a parseable manifest.
|
|
// False on network errors / 404 / malformed JSON. The remaining
|
|
// string fields are empty in that case; `reason` carries a
|
|
// human-readable diagnostic.
|
|
bool manifest_reachable = 7;
|
|
// Empty on success; carries an error description when
|
|
// `manifest_reachable=false`.
|
|
string reason = 8;
|
|
// Manifest URL that was queried (configurable per operator).
|
|
string manifest_url = 9;
|
|
}
|
|
|
|
message SystemAiStatusResponse {
|
|
// True iff `system_llm` is configured AND privacy_mode != off.
|
|
bool enabled = 1;
|
|
// openai / anthropic / "" — empty when disabled.
|
|
string provider = 2;
|
|
// The endpoint URL the operator configured. Empty when disabled.
|
|
string endpoint = 3;
|
|
// Model identifier. Empty when disabled.
|
|
string model = 4;
|
|
// off / redacted / full — never empty.
|
|
string privacy_mode = 5;
|
|
// Name of the env var holding the API key (empty = no auth).
|
|
// Studio's settings page renders the *name*; never the value.
|
|
string api_key_env = 6;
|
|
// Number of cached System-AI explanations currently stored.
|
|
// Surfaced in Doctor + Settings so operators see the cache
|
|
// earning its keep.
|
|
uint64 cache_count = 7;
|
|
}
|
|
|
|
message AskAiRequest {
|
|
// The prompt the operator wants answered. Studio assembles
|
|
// this client-side from the audit event being explained
|
|
// and the chosen privacy mode.
|
|
string prompt = 1;
|
|
// When true, skip the persistent cache and always hit the
|
|
// live provider. Studio's "Regenerate" button passes this so
|
|
// the operator can ask the model to think again.
|
|
bool force_fresh = 2;
|
|
}
|
|
|
|
message AskAiResponse {
|
|
// Failure category, mapped from `system_llm::SystemLlmError`.
|
|
// Empty on success. Studio surfaces each value with a fix hint.
|
|
// Values: "" (success), "disabled", "env_missing", "network",
|
|
// "http", "parse", "empty_response".
|
|
string error_kind = 1;
|
|
// Human-readable diagnostic / answer. Always populated:
|
|
// either the assistant text on success, or the error detail
|
|
// on failure.
|
|
string text = 2;
|
|
// Round-trip latency in milliseconds (success only). For
|
|
// cache hits this is the *original* generation latency, not
|
|
// the cache-lookup time — the UI renders it as "originally
|
|
// took X" so the operator sees what a live call would cost.
|
|
uint32 latency_ms = 3;
|
|
// True iff the answer came from the persistent cache rather
|
|
// than a fresh provider round-trip.
|
|
bool cached = 4;
|
|
// ISO-8601 timestamp the cached entry was first generated.
|
|
// Empty for fresh answers.
|
|
string cached_at = 5;
|
|
// How many times this entry has been served from cache.
|
|
// 0 for fresh answers.
|
|
uint32 cache_hits = 6;
|
|
}
|
|
|
|
message ClearSystemLlmCacheResponse {
|
|
// Number of cached entries that were dropped.
|
|
uint64 purged = 1;
|
|
}
|
|
|
|
message UpdateSystemAiRequest {
|
|
// ollama / openai / lmstudio / vllm / custom (defaults to
|
|
// ollama if empty).
|
|
string provider = 1;
|
|
// Full URL up to and including /v1. Empty + privacy_mode!=off
|
|
// → returns InvalidArgument.
|
|
string endpoint = 2;
|
|
// Model identifier the provider expects. Empty +
|
|
// privacy_mode!=off → returns InvalidArgument.
|
|
string model = 3;
|
|
// Name of the env var holding the API key. Empty = no auth.
|
|
string api_key_env = 4;
|
|
// off / redacted / full. Empty defaults to "off".
|
|
string privacy_mode = 5;
|
|
}
|
|
|
|
message TestSystemAiRequest {
|
|
// Draft system-AI config to probe with. Empty fields fall
|
|
// back to the live in-memory config — handy for "test current
|
|
// settings" without re-sending them.
|
|
string provider = 1;
|
|
string endpoint = 2;
|
|
string model = 3;
|
|
string api_key_env = 4;
|
|
string privacy_mode = 5;
|
|
}
|
|
|
|
message ListSystemAiModelsResponse {
|
|
// Empty on success. Otherwise: same error-kind taxonomy as
|
|
// AskAi (network / http / parse / disabled / env_missing).
|
|
string error_kind = 1;
|
|
string text = 2;
|
|
repeated SystemAiModel models = 3;
|
|
}
|
|
|
|
message SystemAiModel {
|
|
// Model identifier the operator passes as `model:`.
|
|
string id = 1;
|
|
// Optional family / owner string the provider returned.
|
|
string owned_by = 2;
|
|
}
|
|
|
|
message PullSystemAiModelRequest {
|
|
// Draft endpoint + auth. Required; the model is the operator's
|
|
// pick. Currently only Ollama-style /api/pull is supported.
|
|
string endpoint = 1;
|
|
string api_key_env = 2;
|
|
// Model id to pull, e.g. `gemma3:4b`, `llama3.2:3b`.
|
|
string model = 3;
|
|
}
|
|
|
|
message PullSystemAiModelResponse {
|
|
string error_kind = 1;
|
|
string text = 2;
|
|
// Total wall-clock time the pull took, in milliseconds.
|
|
uint32 elapsed_ms = 3;
|
|
}
|
|
|
|
// One message in a PullSystemAiModelStream.
|
|
message PullProgressEvent {
|
|
oneof event {
|
|
// The pull moved on.
|
|
PullProgressUpdate update = 1;
|
|
// Terminal message, success or failure (see its error_kind).
|
|
PullSystemAiModelResponse finished = 2;
|
|
}
|
|
}
|
|
|
|
// A single observation while a model downloads.
|
|
message PullProgressUpdate {
|
|
// The backend's own status text, e.g. "pulling manifest". Passed
|
|
// through verbatim rather than translated: it names layers and
|
|
// digests a client cannot reconstruct.
|
|
string status = 1;
|
|
// Bytes fetched so far for the layer this status refers to.
|
|
uint64 completed = 2;
|
|
// Size of that layer; zero for statuses that carry no size, which
|
|
// clients show as indeterminate rather than as zero progress.
|
|
uint64 total = 3;
|
|
}
|
|
|
|
message HardwareInfoResponse {
|
|
// tiny / small / balanced / large / unknown — see
|
|
// docs/architecture/system-ai.md → "Hardware tiers".
|
|
string tier = 1;
|
|
// CPU brand string, e.g. "Apple M3 Pro".
|
|
string cpu_brand = 2;
|
|
uint32 cpu_cores = 3;
|
|
uint64 ram_mb = 4;
|
|
bool apple_silicon = 5;
|
|
bool dedicated_gpu = 6;
|
|
// Human-readable summary the editor renders verbatim, e.g.
|
|
// "Apple M3 Pro · 16 GB · balanced".
|
|
string summary = 7;
|
|
}
|
|
|
|
message ListSystemAiCuratedModelsResponse {
|
|
repeated CuratedModel models = 1;
|
|
// ISO-date string from models.yaml (e.g. "2026-05-07"). Lets
|
|
// Studio show "curation last reviewed 3 weeks ago".
|
|
string last_reviewed = 2;
|
|
}
|
|
|
|
message CuratedModel {
|
|
string id = 1;
|
|
string family = 2;
|
|
// Parameter count in billions. 0 for closed-source cloud
|
|
// models where we don't publish a number.
|
|
float params_b = 3;
|
|
// basic / good / excellent.
|
|
string quality_tier = 4;
|
|
// tiny / small / balanced / large.
|
|
string min_hw_tier = 5;
|
|
// Context window in K tokens (8 = 8192).
|
|
uint32 context_k = 6;
|
|
// Free-form note rendered as a tooltip in Studio.
|
|
string notes = 7;
|
|
// Licence identifier (gemma-license, apache-2.0, …).
|
|
string license = 8;
|
|
}
|
|
|
|
message ClearEventLogRequest {
|
|
// Operator handle recorded in the chain.reset marker so the
|
|
// discontinuity is attributable. Required.
|
|
string reviewer = 1;
|
|
// Free-form reason recorded in the chain.reset marker. Required —
|
|
// dropping audit events without a reason is the kind of action
|
|
// operators are asked to defend later.
|
|
string reason = 2;
|
|
}
|
|
|
|
message ClearEventLogResponse {
|
|
// Number of events that were purged (excludes the new
|
|
// chain.reset marker that seeds the fresh chain).
|
|
uint64 purged = 1;
|
|
// Channel the operation ran on, echoed back so the CLI can
|
|
// confirm which environment was affected.
|
|
string channel = 2;
|
|
}
|
|
|
|
message SetDefaultScopeRequest {
|
|
// New `default_scope` value. The first entry is the
|
|
// primary scope (the resolver consults the others in order
|
|
// when the primary doesn't match). At least one entry is
|
|
// required; the hub returns InvalidArgument otherwise.
|
|
repeated string scope = 1;
|
|
}
|
|
|
|
message DefaultScopeResponse {
|
|
// The current `default_scope` after the operation.
|
|
repeated string scope = 1;
|
|
// Catalog-known publisher segments the operator may pick
|
|
// from, sorted alphabetically. Surfaces a typeahead-friendly
|
|
// shortlist in the Studio editor; arbitrary entries are
|
|
// still allowed (operator may run a private publisher
|
|
// segment that isn't in the central catalog).
|
|
repeated string known_providers = 2;
|
|
}
|
|
|
|
message ReloadAuthResponse {
|
|
// Number of tokens loaded into the live store after the
|
|
// swap. Operators sanity-check this against the number
|
|
// they expected to have in `auth.tokens:`.
|
|
uint32 token_count = 1;
|
|
}
|
|
|
|
// Guided-setup answers, mirroring chain_core::guided_setup::
|
|
// SetupAnswers (kebab-case wire values, e.g. "trying-out").
|
|
// Unknown values are an INVALID_ARGUMENT — the enums live in Rust.
|
|
message PlanSetupRequest {
|
|
string scenario = 1;
|
|
string intent = 2;
|
|
string target = 3;
|
|
bool require_approval = 4;
|
|
bool data_must_stay_local = 5;
|
|
bool allow_unsigned_modules = 6;
|
|
}
|
|
|
|
// The assembled SetupPlan — field-for-field what `chain init
|
|
// --answers … --plan-json` prints, so a GUI can render the same
|
|
// preview from either source.
|
|
message PlanSetupResponse {
|
|
string profile = 1;
|
|
repeated string modules = 2;
|
|
string starter_flow = 3;
|
|
string runbook = 4;
|
|
repeated string curated_docs = 5;
|
|
bool require_signatures = 6;
|
|
bool worm_audit = 7;
|
|
bool approval_step = 8;
|
|
}
|
|
|
|
message AuthStatusResponse {
|
|
// Validator kind in the on-disk operator config: "static" or
|
|
// "jwt-rs256".
|
|
string validator = 1;
|
|
// True when the hub CURRENTLY accepts anonymous calls — computed
|
|
// from the live validator, not the on-disk config (the two differ
|
|
// until `ReloadAuth` picks up a config edit; see reload_required).
|
|
// Anonymous mode is the static validator with an empty
|
|
// `auth.tokens:` list — the local-dev default.
|
|
bool anonymous_allowed = 2;
|
|
// Static token entries; empty for the jwt-rs256 validator.
|
|
repeated AuthTokenInfo tokens = 3;
|
|
// jwt-rs256 parameters; unset for the static validator.
|
|
JwtValidatorInfo jwt = 4;
|
|
// True when the on-disk auth config (or the env vars it
|
|
// references) no longer produces the validator the hub is
|
|
// enforcing — the operator edited config.yaml or rotated a
|
|
// secret and still needs `ReloadAuth` (or a restart). Also true
|
|
// when the on-disk config is currently invalid.
|
|
bool reload_required = 5;
|
|
}
|
|
|
|
message AuthTokenInfo {
|
|
// Operator-friendly name as it appears in audit-log lines.
|
|
string name = 1;
|
|
// Name of the environment variable holding the secret. The
|
|
// value itself never crosses the wire.
|
|
string token_env = 2;
|
|
// Whether that environment variable is currently set in the
|
|
// daemon's environment — the common rotation footgun.
|
|
bool env_set = 3;
|
|
// Scope grants, verbatim from config (coarse scopes like
|
|
// `read`/`execute`/`admin` and fine-grained T5 patterns like
|
|
// `execute:llm.*`).
|
|
repeated string scopes = 4;
|
|
// Requests-per-minute quota; 0 = unlimited.
|
|
uint32 rate_limit_per_minute = 5;
|
|
}
|
|
|
|
message JwtValidatorInfo {
|
|
// Where the RSA public key comes from: "inline-pem" when the
|
|
// key is embedded in config, else the configured file path.
|
|
string key_source = 1;
|
|
// Required `aud` claim; empty = not checked.
|
|
string audience = 2;
|
|
// Required `iss` claim; empty = not checked.
|
|
string issuer = 3;
|
|
// Claim carrying the caller's scopes.
|
|
string scope_claim = 4;
|
|
}
|
|
|
|
message McpClientConfigEntry {
|
|
// Operator-friendly name. Becomes the second segment of
|
|
// every discovered capability id: `mcp.<name>.<tool>`.
|
|
// Must be unique and not contain dots.
|
|
string name = 1;
|
|
// Endpoint URL. HTTP(S) for streamable-HTTP servers,
|
|
// `stdio://<command>` for local stdio servers.
|
|
string endpoint = 2;
|
|
// Optional env-var name holding a bearer token.
|
|
string api_key_env = 3;
|
|
// Optional human-readable description.
|
|
string description = 4;
|
|
}
|
|
|
|
message ListMcpClientsResponse {
|
|
// Every configured server (regardless of last-discovery
|
|
// outcome).
|
|
repeated McpClientStatus clients = 1;
|
|
}
|
|
|
|
message McpClientStatus {
|
|
McpClientConfigEntry config = 1;
|
|
// Number of tools the last discovery pass returned. 0
|
|
// before discovery has run or on failure.
|
|
uint32 tool_count = 2;
|
|
// Empty on success; otherwise the error_kind taxonomy
|
|
// (`invalid_endpoint`, `not_implemented`, `network`,
|
|
// `http`, `server`, `parse`, `env_missing`).
|
|
string error_kind = 3;
|
|
// Human-readable diagnostic. On success "registered N
|
|
// tools"; on failure the error message.
|
|
string message = 4;
|
|
}
|
|
|
|
message RemoveMcpClientRequest {
|
|
string name = 1;
|
|
}
|
|
|
|
message N8nEndpointConfigEntry {
|
|
string name = 1;
|
|
// Base URL without the /api/v1 suffix.
|
|
string base_url = 2;
|
|
string api_key_env = 3;
|
|
string description = 4;
|
|
}
|
|
|
|
message ListN8nEndpointsResponse {
|
|
repeated N8nEndpointStatus endpoints = 1;
|
|
}
|
|
|
|
message N8nEndpointStatus {
|
|
N8nEndpointConfigEntry config = 1;
|
|
uint32 workflow_count = 2;
|
|
string error_kind = 3;
|
|
string message = 4;
|
|
}
|
|
|
|
message RemoveN8nEndpointRequest {
|
|
string name = 1;
|
|
}
|
|
|
|
message IssueBootstrapTokenRequest {
|
|
// Operator-friendly satellite display name the token enrols.
|
|
string satellite_name = 1;
|
|
// Optional region tag signed into the issued cert at enrollment.
|
|
string region = 2;
|
|
// Token lifetime in seconds; 0 defaults to 24h server-side.
|
|
uint64 ttl_seconds = 3;
|
|
}
|
|
|
|
message IssueBootstrapTokenResponse {
|
|
// The single-use token. Shown once; hand it to the satellite
|
|
// operator over a secure channel.
|
|
string token = 1;
|
|
// ISO-8601 expiry of the token.
|
|
string expires_at = 2;
|
|
// The primary's CA certificate PEM. The operator installs this on
|
|
// the satellite (`federation.primary_ca`) alongside the token so
|
|
// the satellite verifies the primary on its very first connect —
|
|
// closing the first-connect MITM window with no extra lookup.
|
|
string primary_ca_pem = 3;
|
|
}
|
|
|
|
message SatelliteList {
|
|
repeated SatelliteEntry satellites = 1;
|
|
}
|
|
|
|
message SatelliteEntry {
|
|
// Immutable hub UUID of the satellite.
|
|
string hub_id = 1;
|
|
// Operator-chosen display name.
|
|
string display_name = 2;
|
|
// Ch∆In version the satellite reported.
|
|
string hub_version = 3;
|
|
// Negotiated federation wire version.
|
|
uint32 wire_version = 4;
|
|
// Region tag, empty when none.
|
|
string region = 5;
|
|
// Capability ids the satellite currently advertises.
|
|
repeated string capabilities = 6;
|
|
}
|
|
|
|
// ---- Store management (Studio store manager) ----
|
|
|
|
message ListStoresRequest {}
|
|
|
|
message StoreSource {
|
|
// "bundled" for the seed index, else the operator-given name.
|
|
string name = 1;
|
|
// Index URL; empty for the bundled seed.
|
|
string url = 2;
|
|
// False for the bundled seed (cannot be removed).
|
|
bool removable = 3;
|
|
// Modules currently contributed by this source to the live index.
|
|
int32 module_count = 4;
|
|
// True when this store pins a cosign publisher key
|
|
// (`trust.public_key_pem`, or the built-in official key for the
|
|
// bundled seed) — installs from it are verified against that key
|
|
// whenever signature checking is on.
|
|
bool key_pinned = 5;
|
|
}
|
|
|
|
message ListStoresResponse {
|
|
repeated StoreSource stores = 1;
|
|
// Operator policy snapshot so store UIs can say honestly whether
|
|
// installs are signature-checked at all.
|
|
bool require_signatures = 2;
|
|
// Number of globally trusted publisher identities
|
|
// (`security.trusted_publishers`).
|
|
int32 trusted_publisher_count = 3;
|
|
}
|
|
|
|
message AddStoreRequest {
|
|
// Operator-friendly name, unique within configured stores.
|
|
string name = 1;
|
|
// Index URL: https:// , http:// , or file:// .
|
|
string url = 2;
|
|
// Optional bearer-token env var name (hub reads $value at request time).
|
|
string bearer_env = 3;
|
|
// Optional HTTP Basic username.
|
|
string basic_user = 4;
|
|
// Optional HTTP Basic password env var name. Pair with basic_user.
|
|
string basic_password_env = 5;
|
|
// Optional PEM PUBLIC key to pin for this store (cosign key-pinning).
|
|
// When set, signed modules from this store verify against THIS
|
|
// publisher key instead of the global/built-in vendor anchor, so a
|
|
// domain publisher signs with its own key without the vendor master.
|
|
string pinned_pubkey_pem = 6;
|
|
}
|
|
|
|
message AddStoreResponse {
|
|
// Modules the new store contributed to the live index.
|
|
int32 modules_added = 1;
|
|
// Human-readable result (e.g. "added 8 modules from reclaim").
|
|
string message = 2;
|
|
}
|
|
|
|
message RemoveStoreRequest {
|
|
string name = 1;
|
|
}
|
|
|
|
message RemoveStoreResponse {
|
|
bool removed = 1;
|
|
string message = 2;
|
|
}
|