ocm_types/

share.rs

use std::collections::HashMap;

use serde::{Deserialize, Serialize};
use serde_json::{json, Map, Value};

use crate::common::{OcmAddress, ShareType};

#[derive(Debug, PartialEq, Eq, Default, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct NewShare {
    /// Consumer specific identifier of the user, group or federation the provider
    /// wants to share the resource with. This is known in advance.
    /// Please note that the consumer service endpoint is known in advance
    /// as well, so this is no part of the request body.
    /// example: 51dc30ddc473d43a6011e9ebba6ca770@geant.org
    pub share_with: OcmAddress,
    /// Name of the resource (file or folder).
    /// example: resource.txt
    pub name: String,
    /// Optional description of the resource (file or folder).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub description: Option<String>,
    /// Identifier to identify the shared resource at the provider side.
    /// This is unique per provider such that if the same resource is shared twice,
    /// this providerId will not be repeated.
    ///
    /// example: 7c084226-d9a1-11e6-bf26-cec0c932ce01
    pub provider_id: String,
    /// Provider specific identifier of the user who owns the resource.
    ///
    /// example: 6358b71804dfa8ab069cf05ed1b0ed2a@apiwise.nl
    pub owner: OcmAddress,
    /// Provider specific identifier of the user that wants to share the
    /// resource. Please note that the requesting provider is being
    /// identified on a higher level, so the former `remote` property
    /// is not part of the request body.
    ///
    /// example: 527bd5b5d689e2c32ae974c6229ff785@apiwise.nl
    pub sender: OcmAddress,
    /// Display name of the owner of the resource
    /// example: Dimitri
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub owner_display_name: Option<String>,
    /// Display name of the user that wants to share the resource
    /// example: John Doe
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub sender_display_name: Option<String>,
    /// Recipient share type
    pub share_type: ShareType,
    /// Resource type (file, calendar, contact, ...)
    /// example: file
    pub resource_type: String,
    /// The expiration time for the share, in seconds of UTC time since
    /// Unix epoch. If omitted, it is assumed that the share does not expire.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub expiration: Option<i64>,
    /// A nonce to be exchanged for a (potentially short-lived) bearer token
    /// at the Sending Server's `/token` endpoint.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub code: Option<String>,
    pub protocol: Protocol,
}

/// The Sending Server
/// * holds the Resource ("file server" or "Entreprise File Sync and Share (EFSS) server" role), provides access to it (by exposing at least one "API"),
/// * takes the decision to create the Share based on user interface gestures from the Sending Party (the "Authorization Server" role in OAuth)
/// * takes the decision about authorizing attempts to access the Resource (the "Resource Server" role in OAuth)
/// * sends out Share Creation Notifications when appropriate
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct SendingServer(String);

impl NewShare {
    /// Get the Sending Server from the sender of the share.
    pub fn sending_server(&self) ->SendingServer {
        SendingServer(self.owner.get_server_url().into())
    }
}

impl<T: Into<String>> From<T> for SendingServer {
    fn from(value: T) -> Self {
        // FIXME make sure this is a fqdn
        Self(value.into())
    }
}
impl AsRef<str> for SendingServer {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

/// JSON object with specific options for each protocol.
///
/// The supported protocols are:
/// - `webdav`, to access the data
/// - `webapp`, to access remote web applications
/// - `datatx`, to transfer the data to the remote endpoint
///
/// Other custom protocols might be added in the future.
///
/// # Single Protocol Legacy
/// ```
/// use ocm_types::share::Protocol;
/// use serde_json::Map;
/// use serde_json::Value;
/// use serde_json::json;
///
/// #[allow(deprecated)]
/// let single_protocol_legacy = Protocol{
///     name: "webdav".to_string(),
///     options: Some(Map::from_iter(vec![
///         ("sharedSecret".to_string(), Value::String("hfiuhworzwnur98d3wjiwhr".to_string())),
///         ("permissions".to_string(), Value::String("some permissions scheme".to_string())),
///     ].into_iter())),
///     ..Default::default()
/// };
/// let json: Value = serde_json::from_str(r#"{
///     "name": "webdav",
///     "options": {
///         "sharedSecret": "hfiuhworzwnur98d3wjiwhr",
///         "permissions": "some permissions scheme"
///     }
/// }"#).unwrap();
/// assert_eq!(json!(single_protocol_legacy), json);
/// ```
///
/// # Single Protocol New
/// ```
/// use ocm_types::share::Protocol;
/// use ocm_types::share::WebDavProperties;
/// use ocm_types::share::WebDavPermissions;
/// use std::collections::HashMap;
/// use serde_json::Value;
/// use serde_json::json;
///
/// let single_protocol_new = Protocol{
///     name: "multi".to_string(),
///     webdav: Some(WebDavProperties{
///         uri: "7c084226-d9a1-11e6-bf26-cec0c932ce01".to_string(),
///         shared_secret: Some("hfiuhworzwnur98d3wjiwhr".to_string()),
///         permissions: vec![
///             WebDavPermissions::Read,
///             WebDavPermissions::Write,
///         ],
///         requirements: vec![]
///     }),
///     ..Default::default()
/// };
/// let json: Value = serde_json::from_str(r#"{
///     "name": "multi",
///     "webdav": {
///         "uri": "7c084226-d9a1-11e6-bf26-cec0c932ce01",
///         "sharedSecret": "hfiuhworzwnur98d3wjiwhr",
///         "permissions": ["read", "write"]
///     }
/// }"#).unwrap();
/// assert_eq!(json!(single_protocol_new), json);
/// ```
///
/// # Multi Protocol
/// ```
/// use ocm_types::share::Protocol;
/// use ocm_types::share::WebDavProperties;
/// use ocm_types::share::WebDavPermissions;
/// use ocm_types::share::WebDavRequirements;
/// use ocm_types::share::WebAppProperties;
/// use ocm_types::share::WebAppViewMode;
/// use ocm_types::share::DataTxProperties;
/// use std::collections::HashMap;
/// use serde_json::Value;
/// use serde_json::json;
///
/// let single_protocol_new = Protocol{
///     name: "multi".to_string(),
///     webdav: Some(WebDavProperties{
///         uri: "7c084226-d9a1-11e6-bf26-cec0c932ce01".to_string(),
///         shared_secret: Some("hfiuhworzwnur98d3wjiwhr".to_string()),
///         permissions: vec![
///             WebDavPermissions::Read,
///             WebDavPermissions::Write
///         ],
///         requirements: vec![
///             WebDavRequirements::MfaEnforced
///         ]
///     }),
///     webapp: Some(WebAppProperties{
///         uri: "7c084226-d9a1-11e6-bf26-cec0c932ce01".to_string(),
///         shared_secret: Some("hfiuhworzwnur98d3wjiwhr".to_string()),
///         view_mode: WebAppViewMode::Read
///     }),
///     datatx: Some(DataTxProperties{
///         src_uri: "7c084226-d9a1-11e6-bf26-cec0c932ce01".to_string(),
///         shared_secret: "hfiuhworzwnur98d3wjiwhr".to_string(),
///         size: Some(100000)
///     }),
///     ..Default::default()
/// };
/// let json: Value = serde_json::from_str(r#"{
///     "name": "multi",
///     "webdav": {
///         "uri": "7c084226-d9a1-11e6-bf26-cec0c932ce01",
///         "sharedSecret": "hfiuhworzwnur98d3wjiwhr",
///         "permissions": ["read", "write"],
///         "requirements": ["mfa-enforced"]
///     },
///     "webapp": {
///       "uri": "7c084226-d9a1-11e6-bf26-cec0c932ce01",
///       "sharedSecret": "hfiuhworzwnur98d3wjiwhr",
///       "viewMode": "read"
///     },
///     "datatx": {
///      "srcUri": "7c084226-d9a1-11e6-bf26-cec0c932ce01",
///      "sharedSecret": "hfiuhworzwnur98d3wjiwhr",
///      "size": 100000
///     }
/// }"#).unwrap();
/// assert_eq!(json!(single_protocol_new), json);
/// ```
// example:
//   multipleProtocols:
//     name: multi
//     webapp:
//       uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01
//       sharedSecret: hfiuhworzwnur98d3wjiwhr
//       viewMode: read
//     datatx:
//       srcUri: 7c084226-d9a1-11e6-bf26-cec0c932ce01
//       sharedSecret: hfiuhworzwnur98d3wjiwhr
//       size: 100000
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Protocol {
    /// The name of the protocol. Default: `multi`.
    /// If `multi` is given, one or more protocol endpoints are expected
    /// to be defined according to the optional properties specified below.
    /// Otherwise, at least `webdav` is expected to be supported, and
    /// its options MAY be given in the opaque `options` payload for
    /// compatibility with v1.0 implementations (see examples). Note
    /// though that this format is deprecated.
    /// Warning: client implementers should be aware that v1.1 servers
    /// MAY support both `webdav` and `multi`, but v1.0 servers MAY
    /// only support `webdav`.
    /// This field may be removed in a future major version of the spec.
    pub name: String,
    /// This property is now deprecated. Implementations are
    /// encouraged to transition to the new optional properties
    /// defined below, such that this field may be removed in a future major
    /// version of the spec.
    #[deprecated]
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub options: Option<Map<String, Value>>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub webdav: Option<WebDavProperties>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub webapp: Option<WebAppProperties>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub datatx: Option<DataTxProperties>,
    /// Any optional additional protocols supported for this resource
    /// MAY
    /// be provided here, along with their custom payload. Appropriate
    /// capabilities MUST be advertised in order for a sender to ensure
    /// the recipient can parse such customized payloads.
    #[serde(skip_serializing_if = "HashMap::is_empty", default)]
    #[serde(flatten)]
    pub additional_protocols: HashMap<String, Value>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct WebDavProperties {
    /// An URI to access the remote resource. The URI SHOULD be
    /// relative,
    /// such as a key or a UUID, in which case the prefix exposed by the
    /// `/.well-known/ocm` endpoint MUST be used to access the resource,
    /// or it MAY be absolute, including a hostname. The latter is NOT
    /// recommended because of security concerns.
    /// In all cases, for a `folder` resource, the composed URI acts
    /// as the root path, such that other files located within SHOULD
    /// be accessible by appending their relative path to that URI.
    pub uri: String,
    /// An optional secret to be used to access the resource, such
    /// as
    /// a bearer token. If a `code` is provided, it SHOULD be used
    /// instead via the code flow interaction, and the `sharedSecret`
    /// SHOULD be omitted. To prevent leaking it in logs it MUST NOT
    /// appear in any URI.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub shared_secret: Option<String>,
    /// The permissions granted to the sharee.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub permissions: Vec<WebDavPermissions>,
    /// A list of requirements that the recipient provider MUST
    /// fulfill
    /// to access the resource. Requirements are optional, but if it is
    /// present it MUST NOT be empty. A recipient provider MUST reject
    /// a share whose requirements it does not understand.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub requirements: Vec<WebDavRequirements>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum WebDavRequirements {
    /// `mfa-enforced` requires the user accessing the resource to be
    /// MFA-authenticated. This requirement MAY be used if the
    /// recipient provider exposes the `enforce-mfa` capability.
    MfaEnforced,
    /// `use-code` requires the recipient to exchange the given
    /// `code` via a signed HTTPS request to `/token` at the Sending
    /// Server, in order to get a short-lived token to be used for
    /// subsequent access. This requirement MAY be used if the
    /// recipient provider exposes the `receive-code` capability.
    UseCode,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum WebDavPermissions {
    /// allows read-only access including download of a copy.
    Read,
    /// allows create, update, and delete rights on the resource.
    Write,
    /// allows re-share rights on the resource.
    Share,
}

impl TryFrom<WebDavProperties> for Map<String, Value> {
    // FIXME use proper error
    type Error = String;

    fn try_from(value: WebDavProperties) -> Result<Self, Self::Error> {
        let json = json!(value);
        serde_json::from_value(json).map_err(|e| e.to_string())
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct WebAppProperties {
    /// An URI to a client-browsable view of the remote resource,
    /// such that
    /// users may use a web application available at the sender site.
    /// The URI SHOULD be relative, such as a key or a UUID, in which case
    /// the prefix exposed by the `/.well-known/ocm` endpoint MUST be used
    /// to access the resource, or it MAY be absolute, including a hostname.
    /// The latter is NOT recommended because of security concerns.
    /// In all cases, for a `folder` resource, the composed URI acts
    /// as the root path, such that other files located within SHOULD
    /// be accessible by appending their relative path to that URI.
    pub uri: String,
    /// The permissions granted to the sharee.
    pub view_mode: WebAppViewMode,
    /// An optional secret to be used to access the remote web
    /// app, such as
    /// a bearer token. To prevent leaking it in logs it MUST NOT appear
    /// in any URI. If a `code` is provided, then the sending host MUST
    /// accept the short-lived bearer token when serving the web app,
    /// which can be exchanged in the code flow interaction. The exchange
    /// MAY already have happened if the recipient accessed the underlying
    /// resource via WebDAV, in a multi-protocol scenario. In this case,
    /// the `sharedSecret` SHOULD be omitted.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub shared_secret: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum WebAppViewMode {
    /// `read` allows read-only access including download of a copy.
    Read,
    /// `write` allows create, update, and delete rights on the resource.
    Write,
    /// `share` allows re-sharing rights on the resource.
    Share,
}

#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DataTxProperties {
    /// An optional secret to be used to access the resource, such
    /// as
    /// a bearer token. If a `code` is provided, it SHOULD be used
    /// instead via the code flow interaction, and the `sharedSecret`
    /// SHOULD be omitted. To prevent leaking it in logs it MUST NOT
    /// appear in any URI.
    pub shared_secret: String,

    /// An URI to access the resource at the sending server. The
    /// URI
    /// SHOULD be relative, such as a key or a UUID, in which case the
    /// prefix exposed by the `/.well-known/ocm` endpoint SHOULD be used
    /// to access the resource, or it MAY be absolute, including
    /// a hostname. The latter is NOT recommended because of security
    /// concerns.
    pub src_uri: String,
    /// The size of the file to be transferred from the sending server.
    pub size: Option<u64>,
}

/// Consumer successfully received the share. The response might contain
/// the display name of the recipient of the share for general user
/// experience improvement.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ShareCreationResponse {
    /// display name of the recipient
    /// example: John Doe
    pub recipient_display_name: Option<String>,
}