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}
140
141// Why: field names and casing must track Cowork's native `create_artifact`
142// input, so a consumer can read a bundle's `artifacts/<id>.json` and the
143// bridge's staged library records with one parser.
144#[derive(Debug, Serialize)]
145pub struct CoworkLibraryArtifactRecord<'a> {
146    pub id: &'a str,
147    pub name: &'a str,
148    pub description: &'a str,
149    pub version: &'a str,
150    pub content: &'a str,
151    #[serde(rename = "isStarred")]
152    pub is_starred: bool,
153    #[serde(rename = "mcpTools")]
154    pub mcp_tools: &'a [String],
155}
156
157impl<'a> From<&'a ArtifactEntry> for CoworkLibraryArtifactRecord<'a> {
158    fn from(a: &'a ArtifactEntry) -> Self {
159        Self {
160            id: a.id.as_str(),
161            name: &a.name,
162            description: &a.description,
163            version: &a.version,
164            content: &a.content,
165            is_starred: a.starred,
166            mcp_tools: &a.mcp_tools,
167        }
168    }
169}
170
171#[derive(Debug, Clone, Serialize, Deserialize)]
172pub struct SkillEntry {
173    pub id: SkillId,
174    pub name: SkillName,
175    pub description: String,
176    pub file_path: String,
177    #[serde(default)]
178    pub tags: Vec<String>,
179    pub sha256: Sha256Digest,
180    pub instructions: String,
181    #[serde(default, skip_serializing_if = "Vec::is_empty")]
182    pub hosts: Vec<String>,
183}
184
185#[derive(Debug, Clone, Serialize, Deserialize)]
186pub struct AgentEntry {
187    pub id: AgentId,
188    pub name: AgentName,
189    pub display_name: String,
190    pub description: String,
191    pub version: String,
192    pub endpoint: String,
193    pub enabled: bool,
194    pub is_default: bool,
195    pub is_primary: bool,
196    #[serde(default)]
197    pub provider: Option<String>,
198    #[serde(default)]
199    pub model: Option<String>,
200    #[serde(default)]
201    pub mcp_servers: PluginComponentRef,
202    #[serde(default)]
203    pub skills: PluginComponentRef,
204    #[serde(default)]
205    pub tags: Vec<String>,
206    #[serde(default)]
207    pub system_prompt: Option<String>,
208}
209
210#[derive(Debug, Clone, Serialize, Deserialize)]
211pub struct HookEntry {
212    pub id: HookId,
213    pub name: String,
214    pub description: String,
215    pub version: String,
216    pub event: HookEvent,
217    pub matcher: String,
218    pub command: String,
219    #[serde(default)]
220    pub is_async: bool,
221    pub category: HookCategory,
222    #[serde(default)]
223    pub tags: Vec<String>,
224    pub sha256: Sha256Digest,
225}
226
227#[derive(Debug, Clone, Serialize, Deserialize)]
228#[serde(from = "ManagedMcpServerWire")]
229pub struct ManagedMcpServer {
230    pub id: McpServerId,
231    pub name: ManagedMcpServerName,
232    pub url: ValidatedUrl,
233    #[serde(skip_serializing_if = "Option::is_none")]
234    pub transport: Option<String>,
235    #[serde(skip_serializing_if = "Option::is_none")]
236    pub headers: Option<BTreeMap<String, String>>,
237    #[serde(skip_serializing_if = "Option::is_none")]
238    pub oauth: Option<bool>,
239    #[serde(skip_serializing_if = "Option::is_none")]
240    pub tool_policy: Option<BTreeMap<ToolName, ToolPolicy>>,
241}
242
243// Why: manifests signed before the `id` field existed carry only `name`, so
244// deserialization derives an absent id from it.
245#[derive(Deserialize)]
246struct ManagedMcpServerWire {
247    #[serde(default)]
248    id: Option<McpServerId>,
249    name: ManagedMcpServerName,
250    url: ValidatedUrl,
251    #[serde(default)]
252    transport: Option<String>,
253    #[serde(default)]
254    headers: Option<BTreeMap<String, String>>,
255    #[serde(default)]
256    oauth: Option<bool>,
257    #[serde(default)]
258    tool_policy: Option<BTreeMap<ToolName, ToolPolicy>>,
259}
260
261impl From<ManagedMcpServerWire> for ManagedMcpServer {
262    fn from(wire: ManagedMcpServerWire) -> Self {
263        let id = wire
264            .id
265            .unwrap_or_else(|| McpServerId::new(wire.name.as_str()));
266        Self {
267            id,
268            name: wire.name,
269            url: wire.url,
270            transport: wire.transport,
271            headers: wire.headers,
272            oauth: wire.oauth,
273            tool_policy: wire.tool_policy,
274        }
275    }
276}
systemprompt_models/bridge/manifest.rs

systemprompt_models/bridge/
manifest.rs
