pubhubs/api/

auths.rs

//! Additional endpoints provided by the authentication server
use crate::api::*;
use crate::attr::Attr;
use crate::misc::jwt;
use crate::misc::serde_ext::bytes_wrapper::B64UU;
use crate::{attr, handle};

use serde::{Deserialize, Serialize};

use std::collections::HashMap;

use indexmap::IndexMap;

use actix_web::http;

/// Called by the global client to get, for example, the list of supported attribute types.
pub struct WelcomeEP {}
impl EndpointDetails for WelcomeEP {
    type RequestType = NoPayload;
    type ResponseType = Result<WelcomeResp>;

    const METHOD: http::Method = http::Method::GET;
    const PATH: &'static str = ".ph/welcome";
}

/// Reponse type for [`WelcomeEP`].
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
pub struct WelcomeResp {
    /// Available attribute types
    pub attr_types: HashMap<handle::Handle, attr::Type>,

    /// A list of historic values for the duration of the validity of pubhubs cards.
    ///
    /// This field is only set when yivi and historic values for
    /// [`crate::servers::auths::card::CardConfig::valid_for`] are configured.
    ///
    /// The list is guaranteed to be ordered by [`HistoricCardValidity::starting_at_timestamp`],
    /// and is gauranteed to contain an entry with `starting_at_timestamp = 0`.
    #[serde(default)]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub card_validity: Option<Vec<HistoricCardValidity>>,
}

/// Type for [`WelcomeResp::card_validity`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
pub struct HistoricCardValidity {
    /// Starting from this timestamp (number of seconds since 1970-01-01 00:00:00Z)...
    pub starting_at_timestamp: NumericDate,

    /// cards were issued that were valid for this many seconds.
    pub card_valid_for_secs: u64,
}

/// Starts the process of obtaining attributes from the authentication server.
pub struct AuthStartEP {}
impl EndpointDetails for AuthStartEP {
    type RequestType = AuthStartReq;
    type ResponseType = Result<AuthStartResp>;

    const METHOD: http::Method = http::Method::POST;
    const PATH: &'static str = ".ph/auth/start";
}

/// Request type for [`AuthStartEP`].
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
pub struct AuthStartReq {
    /// Which source to use (e.g. yivi)
    pub source: attr::Source,

    /// List of requested attributes.
    ///
    /// Can be non-empty if and only if [`AuthStartReq::attr_type_choices`] is empty.
    /// (Otherwise an [`ErrorCode::BadRequest`] is returned.)
    #[serde(default)]
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub attr_types: Vec<handle::Handle>,

    /// Like [`AuthStartReq::attr_types`], but allow the user to pick each attribute type from a
    /// list.  For example, if `attr_type_choices` is  `[[ph_card, email], [phone]]` that means the
    /// user must disclose either a pubhubs card or an email address, and besides that also a phone
    /// attribute.  
    ///
    /// For [`attr::Source::Yivi`] this results in a 'disjunction' in the disclosure request.
    ///
    /// Note that we do not offer the option to disclose either (`phone` + `email`) or `ph_card`,
    /// because Yivi does not allow `phone` and `email` in an inner conjunction, see
    /// <https://docs.yivi.app/session-requests#multiple-credential-types-within-inner-conjunctions>.
    #[serde(default)]
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub attr_type_choices: Vec<Vec<handle::Handle>>,

    /// Only when [`Self::source`] is `attr::Source::Yivi` can this flag be set.
    /// It makes the [`AuthTask::Yivi::disclosure_request`]  instruct the yivi server to use
    /// [`YIVI_NEXT_SESSION_PATH`] as next `nextSession` url,
    /// see [yivi documentaton](https://docs.yivi.app/chained-sessions/),
    /// making it possible to follow-up the disclosure request with the issuance of a PubHubs card.
    ///
    /// This means that before the dislosure result is returned to the frontend,
    /// the Yivi server will post the disclosure result to the [`YIVI_NEXT_SESSION_PATH`] endpoint
    /// to determine what session to run next.
    ///
    /// Upon receipt of the disclosure result the [`YIVI_NEXT_SESSION_PATH`] endpoint will immediately
    /// make it available via the [`YiviWaitForResultEP`] endpoint, while keeping the Yivi server waiting
    /// for a response which must be provided via the  [`YiviReleaseNextSessionEP`] endpoint.
    ///
    /// This gives the global client time to obtain a PubHubs card issuance request from PubHubs central,
    /// to be passed to the Yivi server as next session via [`YiviReleaseNextSessionEP`].
    #[serde(default)]
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub yivi_chained_session: bool,

    /// Whether to slowly feed the waiting yivi server spaces `" "`, so we can detect when a Yivi
    /// server disconnects.  When `yivi_chained_session_drip` is enabled, we must immediately
    /// return a status code to the Yivi server, and so [`YiviReleaseNextSessionReq::next_session`] can
    /// not be `None`.  This means that using drip we commit to having a next session (e.g. issuing
    /// a PubHubs card).
    #[serde(default)]
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub yivi_chained_session_drip: bool,
}

/// Response to [`AuthStartEP`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub enum AuthStartResp {
    /// Authentication process was started
    Success {
        /// Task for the global client to satisfy the authentication server.
        /// Depends on the requested attribute types
        task: AuthTask,

        /// Opaque state that should be sent with the [`AuthCompleteReq`].
        state: AuthState,
    },

    /// No attribute type known with this handle
    UnknownAttrType(handle::Handle),

    /// The [`AuthStartReq::source`] is not available for the attribute type with this handle
    SourceNotAvailableFor(handle::Handle),

    /// For some reason these two attribute types cannot be requested together
    ///
    /// For [`attr::Source::Yivi`] this might happen if the two attribute types can be derived from
    /// the same [`crate::servers::yivi::AttributeTypeIdentifier`]. This is not something that is currently e
    /// expected to happen.
    Conflict(handle::Handle, handle::Handle),

    /// The authentication server is temporarily at its configured maximum number of concurrent
    /// chained sessions, so it cannot start a new one right now.
    ///
    /// The global client may fall back to the non-chained flow by retrying [`AuthStartEP`] with
    /// `yivi_chained_session` (and `yivi_chained_session_drip`) set to `false`, at the cost of the
    /// user scanning a second Yivi QR for card issuance.
    ChainedSessionsTemporarilyUnavailable,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(transparent)]
pub struct AuthState {
    pub(crate) inner: B64UU,
}

impl AuthState {
    pub(crate) fn new(inner: serde_bytes::ByteBuf) -> Self {
        Self {
            inner: inner.into(),
        }
    }
}

impl std::fmt::Display for AuthState {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.inner.fmt(f)
    }
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
pub enum AuthTask {
    /// Have the end-user disclose to the specified yivi server.
    /// The authentication server only creates the signed (disclosure) session request,
    /// but it's up to the global client to send it to the yivi server.
    Yivi {
        disclosure_request: jwt::JWT,
        yivi_requestor_url: url::Url,
    },
}

/// After having completed the task set by the authentication server,
/// obtain the attributes.
pub struct AuthCompleteEP {}
impl EndpointDetails for AuthCompleteEP {
    type RequestType = AuthCompleteReq;
    type ResponseType = Result<AuthCompleteResp>;

    const METHOD: http::Method = http::Method::POST;
    const PATH: &'static str = ".ph/auth/complete";
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
pub struct AuthCompleteReq {
    /// Proof that the end-user possesses the requested attributes.
    pub proof: AuthProof,

    /// The [`AuthStartResp::Success::state`] obtained earlier.
    pub state: AuthState,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
pub enum AuthProof {
    Yivi {
        /// The JWT returned by the yivi server's `/session/(...)/result-jwt` after completing a session
        /// with [`AuthTask::Yivi::disclosure_request`].
        disclosure: jwt::JWT,
    },
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub enum AuthCompleteResp {
    /// All went well
    Success {
        /// The resulting attributes, in the same order they were requested in
        /// [`AuthStartReq::attr_types`] or [`AuthStartReq::attr_type_choices`].
        /// In the latter case, the key indicates the choice the user made.
        attrs: IndexMap<handle::Handle, Signed<Attr>>,
    },

    /// Something went wrong;  please start again at [`AuthStartEP`].
    ///
    /// One reason is that the authentication server restarted and that the provided authenication
    /// state is no longer valid.
    PleaseRestartAuth,
}

/// Allows the global client to retrieve secrets tied to identifying [`Attr`]ibutes.
///
/// These *attribute keys* are used by the global client to encrypt its  *master secret(s)* before
/// storing them at pubhubs central.
///
/// To allow a compromised attribute key to be replaced (automatically), attribute keys are tied
/// not only to an attribute, but also a timestamp.
pub struct AttrKeysEP {}
impl EndpointDetails for AttrKeysEP {
    type RequestType = HashMap<handle::Handle, AttrKeyReq>;
    type ResponseType = Result<AttrKeysResp>;

    const METHOD: http::Method = http::Method::POST;
    const PATH: &'static str = ".ph/attr-keys";
}

/// Request type for [`AttrKeysEP`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
pub struct AttrKeyReq {
    /// A signed attribute, obtained via [`AuthCompleteEP`].
    ///
    /// The attribute must be identifying.
    pub attr: Signed<Attr>,

    /// If set, will not only return the latest attribute key for `attr`, but also an older
    /// attribute key tied to the given timestamp.
    pub timestamp: Option<NumericDate>,
}

/// Response type for [`AttrKeysEP`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub enum AttrKeysResp {
    /// The attribute with the given handle is not (or no longer) valid.  Reobtain the attribute
    /// and try again.
    RetryWithNewAttr(handle::Handle),

    /// Successfully retrieves keys for all attributes provided.
    Success(HashMap<handle::Handle, AttrKeyResp>),
}

/// Part of a successful [`AttrKeyResp`].
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub struct AttrKeyResp {
    /// A pair, `(key, timestamp)`, where `key` is the latest attribute key for the requested attribute
    /// and `timestamp` can be used to retrieve the same key again later on by setting `AttrKeyReq::timestamp`.
    pub latest_key: (B64UU, NumericDate),

    /// The attribute key at [`AttrKeyReq::timestamp`], when this was set.
    ///
    /// This key should only be use for decryption, not for encryption.
    pub old_key: Option<B64UU>,
}

/// Request a pubhubs card, or rather, a signed session request for the issuance of a pubhubs card
/// that can be passed to the authentication server's yivi server to actually issue the card.
pub struct CardEP {}
impl EndpointDetails for CardEP {
    type RequestType = CardReq;
    type ResponseType = Result<CardResp>;

    const METHOD: http::Method = http::Method::POST;
    const PATH: &'static str = ".ph/card";
}

/// Request type for [`CardEP`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub struct CardReq {
    /// A by PHC signed registration pseudonym obtained via [`phc::user::CardPseudEP`].
    pub card_pseud_package: Signed<phc::user::CardPseudPackage>,

    /// Optional comment used after the registration date field.
    /// Could perhaps be the partly anonymized email address and phone number used to originally
    /// register this account.
    pub comment: Option<String>,
}

/// What's returned by [`CardEP`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub enum CardResp {
    Success {
        /// Attribute for the card that can be added to the user's account via the
        /// [`phc::user::EnterEP`] endpoint.
        ///
        /// Make sure that you first add this attribute to the user's account before you add the
        /// card to the user's yivi app - we do not want to end up with a card in the yivi app that
        /// is not connected to the user's account.
        attr: Signed<Attr>,

        /// Signed issuance request to issue the pubhubs card.  Can be used to start a new session
        /// with the Yivi server directly, or an already existing chained session with the
        /// authentication server, via [`YiviReleaseNextSessionEP`].
        ///
        /// Before making the issuance request, make sure [`CardResp::Success::attr`] is added to the
        /// user's account!
        issuance_request: jwt::JWT,

        /// The Yivi server that can handle the issuance request
        yivi_requestor_url: url::Url,
    },

    /// Please try again with a new signed card pseudonym package
    PleaseRetryWithNewCardPseud,
}

/// Wait for the disclosure result that the yivi server will post to the authentication server
///
/// Might return [`ErrorCode::BadRequest`] when yivi is not configured for this authentication
/// server, or when [`AuthStartReq::yivi_chained_session`] was not set for [`YiviWaitForResultReq::state`].
pub struct YiviWaitForResultEP {}
impl EndpointDetails for YiviWaitForResultEP {
    type RequestType = YiviWaitForResultReq;
    type ResponseType = Result<YiviWaitForResultResp>;

    const METHOD: http::Method = http::Method::POST;
    const PATH: &'static str = ".ph/yivi/wait-for-result";
}

/// Request type for [`YiviWaitForResultEP`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub struct YiviWaitForResultReq {
    /// The [`AuthStartResp::Success::state`] returned earlier
    pub state: AuthState,
}

/// What's returned by [`YiviWaitForResultEP`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub enum YiviWaitForResultResp {
    Success {
        /// The disclosure result posted by the Yivi server
        disclosure: jwt::JWT,
    },

    /// Something went wrong;  please start again at [`AuthStartEP`].
    ///
    /// One reason is that the authentication server restarted and that the provided authenication
    /// state is no longer valid.
    PleaseRestartAuth,

    /// The request seems fine, but the session cannot be found.  Either the session expired, or
    /// was already completed.  Could caused by a logic error in the client, but also by a slow
    /// internet connection.
    SessionGone,
}

/// Provide the waiting yivi server with the next session.
pub struct YiviReleaseNextSessionEP {}
impl EndpointDetails for YiviReleaseNextSessionEP {
    type RequestType = YiviReleaseNextSessionReq;
    type ResponseType = Result<YiviReleaseNextSessionResp>;

    const METHOD: http::Method = http::Method::POST;
    const PATH: &'static str = ".ph/yivi/release-next-session";
}

/// Request type for [`YiviReleaseNextSessionEP`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub struct YiviReleaseNextSessionReq {
    /// The [`AuthStartResp::Success::state`] returned earlier
    pub state: AuthState,

    /// Instructs the authentication server on what next session (if any) to start at the yivi server.
    ///
    /// If `None` the yivi server will be served a `HTTP 204` causing it to stop the yivi flow
    /// normally without opening a follow-up session.
    ///
    /// Otherwise it must be some signed session request that will be passed to yivi server.
    /// This session request must be signed by the authentication server's yivi requestor credentials,
    /// for example, [`CardResp::Success::issuance_request`].
    ///
    /// The value `None` is not permitted when [`AuthStartReq::yivi_chained_session_drip`]
    /// was set (because in that case the HTTP status code `200` has already been sent to the Yivi server.)
    /// If `None` is submitted anyway, this causes an `ErrorCode::BadRequest`.
    pub next_session: Option<jwt::JWT>,

    /// If the yivi server has been waiting more than this amount of milliseconds when it is about to be released,
    /// dont release it, but ghost it.
    /// The reason is that drip mechanism may be too slow to detect the yivi server timing out.
    #[serde(default)]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stale_after: Option<u16>,
}

/// What's returned by [`YiviReleaseNextSessionEP`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub enum YiviReleaseNextSessionResp {
    Success {},

    /// Something went wrong;  please start again at [`AuthStartEP`].
    ///
    /// One reason is that the authentication server restarted and that the provided authenication
    /// state is no longer valid.
    PleaseRestartAuth,

    /// The request seems fine, but the session cannot be found.  Either the session expired, or
    /// was already completed.  Could caused by a logic error in the client, but also by a slow
    /// internet connection.
    SessionGone,

    /// The request seems fine, but the Yivi server is gone, perhaps because it timed out.
    /// Also returned when the authentication server deems the yivi server stale, see [`YiviReleaseNextSessionReq::stale_after`].
    YiviServerGone,

    /// Trying to release a yivi server that's not there yet.  You should first call the
    /// [`YiviWaitForResultEP`] endpoint to make sure the yivi server is there.
    TooEarly,
}

/// Path for the endpoint used by the yivi server to get the next session in a chained session.
///
/// Note that this endpoint does not conform to the [`EndpointDetails`] format, using, for example,
/// the HTTP status code to convey information (`204` means no next session).
pub const YIVI_NEXT_SESSION_PATH: &str = ".ph/yivi/next-session";

/// Query parameters to the [`YIVI_NEXT_SESSION_PATH`] endpoint.
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
#[must_use]
pub struct YiviNextSessionQuery {
    pub state: AuthState,
}