systemprompt_models/bridge/
manifest.rs

1//! Signed manifest wire format.
2//!
3//! `GET /v1/bridge/manifest` returns a [`SignedManifestEnvelope`]: the
4//! JCS-canonical serialization of a [`SignedManifest`] carried verbatim as
5//! `payload`, plus a detached ed25519 signature over those exact bytes. The
6//! bridge verifies the signature against the raw `payload` string *before*
7//! deserialising it, so fields added to [`SignedManifest`] in newer gateways
8//! never invalidate the signature on older bridges — unknown fields are
9//! simply ignored at parse time. Semantic breaks that an older bridge cannot
10//! safely ignore are declared by raising `min_schema_version` above
11//! [`MANIFEST_SCHEMA_VERSION`] of the consuming bridge, which then refuses
12//! with an upgrade message instead of a signature error.
13//!
14//! Signing, signature verification, and manifest construction live in
15//! the bridge crate (`bin/bridge/src/gateway/manifest.rs`) alongside
16//! the gateway client. Those layers pull in `ed25519-dalek` and
17//! `serde_jcs` which are not appropriate dependencies for this
18//! foundation crate.
19//!
20//! Copyright (c) systemprompt.io — Business Source License 1.1.
21//! See <https://systemprompt.io> for licensing details.
22
23use std::collections::BTreeMap;
24
25use serde::{Deserialize, Serialize};
26
27pub use crate::bridge::ids::ManifestSignature;
28use crate::bridge::ids::{
29    LibraryArtifactId, ManagedMcpServerName, PluginId, Sha256Digest, SkillId, SkillName, ToolName,
30    ToolPolicy,
31};
32use crate::bridge::manifest_version::ManifestVersion;
33use crate::services::hooks::{HookCategory, HookEvent};
34use crate::services::plugin::{PluginComponentRef, PluginHooksRef};
35use systemprompt_identifiers::{
36    AgentId, AgentName, HookId, McpServerId, TenantId, UserId, ValidatedUrl,
37};
38
39pub const MANIFEST_SCHEMA_VERSION: u32 = 1;
40
41// Why: not tied to the release version, and never swept by a version-bump
42// script. Raising it strands every client below it until they update, so it
43// moves only when the gateway makes a change an older bridge cannot handle.
44pub const MIN_BRIDGE_VERSION: &str = "0.28.0";
45
46#[must_use]
47pub fn bridge_version_is_supported(reported: &str, floor: &str) -> bool {
48    match (
49        semver::Version::parse(reported),
50        semver::Version::parse(floor),
51    ) {
52        (Ok(reported), Ok(floor)) => reported >= floor,
53        // Why: an unparseable version is almost always a local dev build;
54        // refusing those would make the gateway untestable against a work tree.
55        _ => true,
56    }
57}
58
59#[derive(Debug, Clone, Serialize, Deserialize)]
60pub struct SignedManifestEnvelope {
61    pub payload: String,
62    pub signature: ManifestSignature,
63}
64
65#[derive(Debug, Clone, Serialize, Deserialize)]
66pub struct SignedManifest {
67    #[serde(default)]
68    pub min_schema_version: u32,
69    #[serde(default)]
70    pub min_bridge_version: Option<String>,
71    pub manifest_version: ManifestVersion,
72    pub issued_at: String,
73    pub not_before: String,
74    pub user_id: UserId,
75    pub tenant_id: Option<TenantId>,
76    #[serde(default)]
77    pub user: Option<UserInfo>,
78    pub plugins: Vec<PluginEntry>,
79    #[serde(default)]
80    pub skills: Vec<SkillEntry>,
81    #[serde(default)]
82    pub agents: Vec<AgentEntry>,
83    #[serde(default)]
84    pub hooks: Vec<HookEntry>,
85    pub managed_mcp_servers: Vec<ManagedMcpServer>,
86    pub revocations: Vec<String>,
87    #[serde(default)]
88    pub enabled_hosts: Vec<String>,
89    #[serde(default)]
90    pub host_model_protocols: BTreeMap<String, Vec<String>>,
91    #[serde(default)]
92    pub artifacts: Vec<ArtifactEntry>,
93    #[serde(default)]
94    pub allow_claude_ai_connectors: bool,
95    #[serde(default, skip_serializing_if = "Vec::is_empty")]
96    pub diagnostics: Vec<String>,
97}
98
99#[derive(Debug, Clone, Serialize, Deserialize)]
100pub struct UserInfo {
101    pub id: UserId,
102    pub name: String,
103    pub email: String,
104    #[serde(default)]
105    pub display_name: Option<String>,
106    #[serde(default)]
107    pub roles: Vec<String>,
108}
109
110#[derive(Debug, Clone, Serialize, Deserialize)]
111pub struct PluginEntry {
112    pub id: PluginId,
113    pub version: String,
114    pub sha256: Sha256Digest,
115    pub files: Vec<PluginFile>,
116    #[serde(default)]
117    pub hooks: PluginHooksRef,
118}
119
120#[derive(Debug, Clone, Serialize, Deserialize)]
121pub struct PluginFile {
122    pub path: String,
123    pub sha256: Sha256Digest,
124    pub size: u64,
125}
126
127/// A Cowork-native library document (raw HTML in the desktop app's Artifacts
128/// library) — not one of the in-chat MCP artifacts in [`crate::artifacts`].
129#[derive(Debug, Clone, Serialize, Deserialize)]
130pub struct ArtifactEntry {
131    pub id: LibraryArtifactId,
132    pub name: String,
133    pub description: String,
134    pub version: String,
135    pub mcp_tools: Vec<String>,
136    pub content: String,
137    pub starred: bool,
138    pub sha256: Sha256Digest,
139    // Why: grouping context for the bridge's Marketplace listing; empty on a
140    // manifest built before this field existed, which renders ungrouped.
141    #[serde(default, skip_serializing_if = "Vec::is_empty")]
142    pub plugins: Vec<PluginId>,
143}
144
145#[derive(Debug, Clone, Serialize, Deserialize)]
146pub struct SkillEntry {
147    pub id: SkillId,
148    pub name: SkillName,
149    pub description: String,
150    pub file_path: String,
151    #[serde(default)]
152    pub tags: Vec<String>,
153    pub sha256: Sha256Digest,
154    pub instructions: String,
155    #[serde(default, skip_serializing_if = "Vec::is_empty")]
156    pub hosts: Vec<String>,
157    // Why: see `ArtifactEntry::plugins` — same grouping context, same
158    // empty-means-ungrouped fallback.
159    #[serde(default, skip_serializing_if = "Vec::is_empty")]
160    pub plugins: Vec<PluginId>,
161}
162
163#[derive(Debug, Clone, Serialize, Deserialize)]
164pub struct AgentEntry {
165    pub id: AgentId,
166    pub name: AgentName,
167    pub display_name: String,
168    pub description: String,
169    pub version: String,
170    pub endpoint: String,
171    pub enabled: bool,
172    pub is_default: bool,
173    pub is_primary: bool,
174    #[serde(default)]
175    pub provider: Option<String>,
176    #[serde(default)]
177    pub model: Option<String>,
178    #[serde(default)]
179    pub mcp_servers: PluginComponentRef,
180    #[serde(default)]
181    pub skills: PluginComponentRef,
182    #[serde(default)]
183    pub tags: Vec<String>,
184    #[serde(default)]
185    pub system_prompt: Option<String>,
186}
187
188#[derive(Debug, Clone, Serialize, Deserialize)]
189pub struct HookEntry {
190    pub id: HookId,
191    pub name: String,
192    pub description: String,
193    pub version: String,
194    pub event: HookEvent,
195    pub matcher: String,
196    pub command: String,
197    #[serde(default)]
198    pub is_async: bool,
199    pub category: HookCategory,
200    #[serde(default)]
201    pub tags: Vec<String>,
202    pub sha256: Sha256Digest,
203}
204
205#[derive(Debug, Clone, Serialize, Deserialize)]
206#[serde(from = "ManagedMcpServerWire")]
207pub struct ManagedMcpServer {
208    pub id: McpServerId,
209    pub name: ManagedMcpServerName,
210    pub url: ValidatedUrl,
211    #[serde(skip_serializing_if = "Option::is_none")]
212    pub transport: Option<String>,
213    #[serde(skip_serializing_if = "Option::is_none")]
214    pub headers: Option<BTreeMap<String, String>>,
215    #[serde(skip_serializing_if = "Option::is_none")]
216    pub oauth: Option<bool>,
217    #[serde(skip_serializing_if = "Option::is_none")]
218    pub tool_policy: Option<BTreeMap<ToolName, ToolPolicy>>,
219}
220
221// Why: manifests signed before the `id` field existed carry only `name`, so
222// deserialization derives an absent id from it.
223#[derive(Deserialize)]
224struct ManagedMcpServerWire {
225    #[serde(default)]
226    id: Option<McpServerId>,
227    name: ManagedMcpServerName,
228    url: ValidatedUrl,
229    #[serde(default)]
230    transport: Option<String>,
231    #[serde(default)]
232    headers: Option<BTreeMap<String, String>>,
233    #[serde(default)]
234    oauth: Option<bool>,
235    #[serde(default)]
236    tool_policy: Option<BTreeMap<ToolName, ToolPolicy>>,
237}
238
239impl From<ManagedMcpServerWire> for ManagedMcpServer {
240    fn from(wire: ManagedMcpServerWire) -> Self {
241        let id = wire
242            .id
243            .unwrap_or_else(|| McpServerId::new(wire.name.as_str()));
244        Self {
245            id,
246            name: wire.name,
247            url: wire.url,
248            transport: wire.transport,
249            headers: wire.headers,
250            oauth: wire.oauth,
251            tool_policy: wire.tool_policy,
252        }
253    }
254}
systemprompt_models/bridge/manifest.rs

systemprompt_models/bridge/
manifest.rs
