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}
182
183#[derive(Debug, Clone, Serialize, Deserialize)]
184pub struct AgentEntry {
185    pub id: AgentId,
186    pub name: AgentName,
187    pub display_name: String,
188    pub description: String,
189    pub version: String,
190    pub endpoint: String,
191    pub enabled: bool,
192    pub is_default: bool,
193    pub is_primary: bool,
194    #[serde(default)]
195    pub provider: Option<String>,
196    #[serde(default)]
197    pub model: Option<String>,
198    #[serde(default)]
199    pub mcp_servers: PluginComponentRef,
200    #[serde(default)]
201    pub skills: PluginComponentRef,
202    #[serde(default)]
203    pub tags: Vec<String>,
204    #[serde(default)]
205    pub system_prompt: Option<String>,
206}
207
208#[derive(Debug, Clone, Serialize, Deserialize)]
209pub struct HookEntry {
210    pub id: HookId,
211    pub name: String,
212    pub description: String,
213    pub version: String,
214    pub event: HookEvent,
215    pub matcher: String,
216    pub command: String,
217    #[serde(default)]
218    pub is_async: bool,
219    pub category: HookCategory,
220    #[serde(default)]
221    pub tags: Vec<String>,
222    pub sha256: Sha256Digest,
223}
224
225#[derive(Debug, Clone, Serialize, Deserialize)]
226#[serde(from = "ManagedMcpServerWire")]
227pub struct ManagedMcpServer {
228    pub id: McpServerId,
229    pub name: ManagedMcpServerName,
230    pub url: ValidatedUrl,
231    #[serde(skip_serializing_if = "Option::is_none")]
232    pub transport: Option<String>,
233    #[serde(skip_serializing_if = "Option::is_none")]
234    pub headers: Option<BTreeMap<String, String>>,
235    #[serde(skip_serializing_if = "Option::is_none")]
236    pub oauth: Option<bool>,
237    #[serde(skip_serializing_if = "Option::is_none")]
238    pub tool_policy: Option<BTreeMap<ToolName, ToolPolicy>>,
239}
240
241// Why: manifests signed before the `id` field existed carry only `name`, so
242// deserialization derives an absent id from it.
243#[derive(Deserialize)]
244struct ManagedMcpServerWire {
245    #[serde(default)]
246    id: Option<McpServerId>,
247    name: ManagedMcpServerName,
248    url: ValidatedUrl,
249    #[serde(default)]
250    transport: Option<String>,
251    #[serde(default)]
252    headers: Option<BTreeMap<String, String>>,
253    #[serde(default)]
254    oauth: Option<bool>,
255    #[serde(default)]
256    tool_policy: Option<BTreeMap<ToolName, ToolPolicy>>,
257}
258
259impl From<ManagedMcpServerWire> for ManagedMcpServer {
260    fn from(wire: ManagedMcpServerWire) -> Self {
261        let id = wire
262            .id
263            .unwrap_or_else(|| McpServerId::new(wire.name.as_str()));
264        Self {
265            id,
266            name: wire.name,
267            url: wire.url,
268            transport: wire.transport,
269            headers: wire.headers,
270            oauth: wire.oauth,
271            tool_policy: wire.tool_policy,
272        }
273    }
274}
systemprompt_models/bridge/manifest.rs

systemprompt_models/bridge/
manifest.rs
