Skip to main content

subc_protocol/scope/
authorize.rs

1use serde::{Deserialize, Serialize};
2
3use super::{deserialize_scope_principal, ScopeAttributes, ScopeKind};
4use crate::Principal;
5
6/// Only the configured federated owner may provide this authorization oracle.
7pub const ROUTE_AUTHORIZE_CAPABILITY: &str = "route-authorize/v1";
8pub const ROUTE_AUTHORIZE_OP: &str = "route.authorize";
9
10/// A stored scope identity, never a bind proof or an unpinned selector.
11#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
12#[serde(deny_unknown_fields)]
13#[non_exhaustive]
14pub struct RouteAuthorizeScope {
15    #[serde(deserialize_with = "deserialize_scope_principal")]
16    pub owner: Principal,
17    #[serde(rename = "ref")]
18    pub scope_ref: String,
19    pub epoch: u64,
20}
21
22impl RouteAuthorizeScope {
23    pub fn new(owner: Principal, scope_ref: impl Into<String>, epoch: u64) -> Self {
24        Self {
25            owner,
26            scope_ref: scope_ref.into(),
27            epoch,
28        }
29    }
30}
31
32/// Claim derivation inputs. Missing fields must also be absent on the scope;
33/// they are not wildcards. Like a stamp, omitted `delegates` means false.
34#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
35#[serde(deny_unknown_fields)]
36#[non_exhaustive]
37pub struct RouteAuthorizeExpected {
38    pub kind: ScopeKind,
39    #[serde(default, skip_serializing_if = "Option::is_none")]
40    pub agent_id: Option<String>,
41    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
42    pub delegates: bool,
43    #[serde(default, skip_serializing_if = "Option::is_none")]
44    pub run_id: Option<String>,
45    #[serde(default, skip_serializing_if = "Option::is_none")]
46    pub on_behalf_of_agent: Option<String>,
47    #[serde(default, skip_serializing_if = "Option::is_none")]
48    pub flow_id: Option<String>,
49    #[serde(default, skip_serializing_if = "Option::is_none")]
50    pub flow_version: Option<u64>,
51    #[serde(default, skip_serializing_if = "Option::is_none")]
52    pub flow_install_id: Option<String>,
53    #[serde(default, skip_serializing_if = "Option::is_none")]
54    pub flow_code_hash: Option<String>,
55}
56
57impl RouteAuthorizeExpected {
58    pub fn new(kind: ScopeKind, attributes: &ScopeAttributes) -> Self {
59        Self {
60            kind,
61            agent_id: attributes.agent_id.clone(),
62            delegates: attributes.delegates,
63            run_id: attributes.run_id.clone(),
64            on_behalf_of_agent: attributes.on_behalf_of_agent.clone(),
65            flow_id: attributes.flow_id.clone(),
66            flow_version: attributes.flow_version,
67            flow_install_id: attributes.flow_install_id.clone(),
68            flow_code_hash: attributes.flow_code_hash.clone(),
69        }
70    }
71}
72
73#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
74#[serde(rename_all = "snake_case")]
75#[non_exhaustive]
76pub enum RouteAuthorizeOutcome {
77    /// Not a promise that a later open succeeds: transient availability checks
78    /// can still refuse it without sending a bind to the provider.
79    Authorized,
80    ScopeEnded,
81    Indeterminate,
82    EpochChanged,
83    ClaimChanged,
84    ProofRequired,
85    NotAuthorized,
86    TargetAbsent,
87}
88
89#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
90#[non_exhaustive]
91pub struct RouteAuthorizeResponse {
92    op: RouteAuthorizeOp,
93    pub outcome: RouteAuthorizeOutcome,
94    #[serde(default, skip_serializing_if = "Option::is_none")]
95    pub content_version: Option<String>,
96    #[serde(default, skip_serializing_if = "Option::is_none")]
97    pub route_open_code: Option<String>,
98    pub message: String,
99}
100
101#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
102enum RouteAuthorizeOp {
103    #[serde(rename = "route.authorize")]
104    Authorize,
105}
106
107impl RouteAuthorizeResponse {
108    pub fn new(outcome: RouteAuthorizeOutcome, message: impl Into<String>) -> Self {
109        Self {
110            op: RouteAuthorizeOp::Authorize,
111            outcome,
112            content_version: None,
113            route_open_code: None,
114            message: message.into(),
115        }
116    }
117}
118
119#[cfg(test)]
120mod tests {
121    use super::*;
122    use serde_json::json;
123
124    #[test]
125    fn route_authorize_expected_is_closed_and_absence_is_not_a_wildcard() {
126        let expected: RouteAuthorizeExpected =
127            serde_json::from_value(json!({"kind":"head"})).unwrap();
128        assert_ne!(
129            expected,
130            RouteAuthorizeExpected::new(
131                ScopeKind::Head,
132                &ScopeAttributes::new().with_agent_id(Some("agent".into()))
133            )
134        );
135        assert!(serde_json::from_value::<RouteAuthorizeExpected>(
136            json!({"kind":"head","agent_name":"display"})
137        )
138        .is_err());
139        let response = serde_json::to_value(RouteAuthorizeResponse::new(
140            RouteAuthorizeOutcome::ClaimChanged,
141            "changed",
142        ))
143        .unwrap();
144        assert_eq!(
145            response,
146            json!({"op":"route.authorize","outcome":"claim_changed","message":"changed"})
147        );
148    }
149}