navcore_signalk_client/

access.rs

//! Being let in.
//!
//! With security switched on, a device asks for a token and a human
//! approves it once:
//!
//! 1. `POST /signalk/v1/access/requests` with a client id, a description
//!    and the permissions wanted. Answers `202` with a request id.
//! 2. `GET /signalk/v1/requests/<id>` -- `PENDING` until somebody decides.
//! 3. The administrator approves it in the server's own interface.
//! 4. The same GET then answers `COMPLETED` and carries the token.
//!
//! The token goes in an `Authorization: Bearer` header afterwards and is
//! good for as long as the administrator said. Storing it is the
//! application's business, not this crate's.
//!
//! # Whether a token is needed to read at all
//!
//! With security on, the REST interface refuses an unauthenticated
//! request with `401`. The data stream is governed separately, by the
//! server's `allowReadonly` setting: it decides whether a device can
//! draw a chart before anybody has approved it. Publishing routes
//! always needs a token either way.
//!
//! When `allowReadonly` is off, an unauthenticated client still
//! connects and still receives the greeting, complete with the
//! vessel's identifier, then receives nothing further -- indistinguishable
//! on the wire from a boat whose instruments are switched off. A client
//! with no token should report that itself rather than wait to be
//! told, since it never will be.

use std::time::Duration;

use crate::{ClientError, Trust};

/// How long to wait for the server to answer one call.
const TIMEOUT: Duration = Duration::from_secs(10);

/// What the mariner is asking to be allowed to do.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Permissions {
    /// Enough to draw the chart: everything the server publishes.
    ReadOnly,
    /// Also enough to publish routes and to steer the course API.
    ReadWrite,
}

impl Permissions {
    fn as_str(self) -> &'static str {
        match self {
            Self::ReadOnly => "readonly",
            Self::ReadWrite => "readwrite",
        }
    }
}

/// A request that is now in front of whoever administers the server.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PendingRequest {
    /// What to ask about later.
    pub request_id: String,
}

/// What became of asking for access.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Requested {
    /// A fresh request now sits in front of the administrator.
    New(PendingRequest),
    /// The server already holds an unanswered request under this
    /// `clientId`. Not a failure of this call -- the device's place in the
    /// queue was never lost, only this particular attempt to make a second
    /// one. There is no `PendingRequest` to poll here: the server's answer
    /// carries no usable id for it (see the module doc), so this is a state
    /// to display, not a request to check on.
    AlreadyPending,
}

/// Where a request has got to.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Access {
    /// Nobody has decided yet.
    Pending,
    /// Approved, with the token to use from now on.
    Approved {
        /// The bearer token.
        token: String,
    },
    /// Refused. Not an error -- an answer.
    Denied,
}

/// Asks a server for a token.
///
/// `client_id` identifies this installation and must stay the same across
/// restarts: it is what the administrator sees in the list, and asking
/// again under a new name would put a second entry in front of them.
///
/// Asking again under the *same* name while an earlier request is still
/// unanswered is refused by the server -- restarting mid-wait reaches
/// this, not just misuse -- and comes back as
/// [`Requested::AlreadyPending`] rather than as an error, since it is
/// functionally the same situation as still waiting, not a new kind of
/// failure.
///
/// # Errors
///
/// If the server cannot be reached, or answers something this cannot make
/// sense of at all.
pub fn request_access(
    http_base: &str,
    client_id: &str,
    description: &str,
    permissions: Permissions,
    trust: &Trust,
) -> Result<Requested, ClientError> {
    let body = serde_json::json!({
        "clientId": client_id,
        "description": description,
        "permissions": permissions.as_str(),
    });

    // The server's answer to a clash is meaningful, not just a status code
    // to react to -- it names exactly this situation in `message`. Reading
    // it needs the body of a 4xx response, which ureq discards by default
    // in favour of turning it straight into an error.
    let mut response = agent(trust)?
        .post(&format!("{http_base}/signalk/v1/access/requests"))
        .config()
        .http_status_as_error(false)
        .build()
        .send_json(&body)
        .map_err(|error| ClientError::Http(error.to_string()))?;

    let answer: serde_json::Value = response
        .body_mut()
        .read_json()
        .map_err(|error| ClientError::Http(error.to_string()))?;

    read_requested(&answer)
}

/// Reads one answer to a fresh access request.
///
/// `state` is what tells a usable request apart from a refused one, not
/// whether a `requestId` is present -- a request refused outright (a
/// validation failure, or the clash this exists to recognise) still names
/// the id of the now-dead request it refused, and polling that would not
/// time out and would not error, only sit at `Pending` forever. A human
/// approves nothing synchronously with the `POST`, so `PENDING` is the only
/// state a fresh, pollable request is ever found in.
fn read_requested(answer: &serde_json::Value) -> Result<Requested, ClientError> {
    let message = answer.get("message").and_then(serde_json::Value::as_str);

    if answer.get("state").and_then(serde_json::Value::as_str) == Some("PENDING") {
        return answer
            .get("requestId")
            .and_then(serde_json::Value::as_str)
            .map(|request_id| {
                Requested::New(PendingRequest {
                    request_id: request_id.to_owned(),
                })
            })
            .ok_or_else(|| ClientError::Protocol(format!("no requestId in {answer}")));
    }

    // Refused outright. Recognised by what the server actually said, not
    // guessed at from the status code alone.
    if answer.get("statusCode").and_then(serde_json::Value::as_u64) == Some(400)
        && message.is_some_and(|text| text.contains("already requested access"))
    {
        return Ok(Requested::AlreadyPending);
    }

    Err(ClientError::Protocol(message.map_or_else(
        || format!("could not ask for access: {answer}"),
        str::to_owned,
    )))
}

/// Asks what became of a request.
///
/// # Errors
///
/// If the server cannot be reached, or answers something unreadable.
pub fn check_access(
    http_base: &str,
    request: &PendingRequest,
    trust: &Trust,
) -> Result<Access, ClientError> {
    let answer: serde_json::Value = agent(trust)?
        .get(&format!(
            "{http_base}/signalk/v1/requests/{}",
            request.request_id
        ))
        .call()
        .map_err(|error| ClientError::Http(error.to_string()))?
        .body_mut()
        .read_json()
        .map_err(|error| ClientError::Http(error.to_string()))?;

    Ok(read_access(&answer))
}

/// Reads one answer to a request enquiry.
fn read_access(answer: &serde_json::Value) -> Access {
    if answer.get("state").and_then(serde_json::Value::as_str) != Some("COMPLETED") {
        return Access::Pending;
    }

    let request = answer.get("accessRequest");
    let permission = request
        .and_then(|request| request.get("permission"))
        .and_then(serde_json::Value::as_str);
    let token = request
        .and_then(|request| request.get("token"))
        .and_then(serde_json::Value::as_str);

    match (permission, token) {
        (Some("APPROVED"), Some(token)) => Access::Approved {
            token: token.to_owned(),
        },
        // Approved but tokenless should not happen; treated as a refusal
        // rather than as an approval, because acting on the optimistic
        // reading would mean connecting with no credentials at all.
        (Some("APPROVED"), None) | (Some(_), _) => Access::Denied,
        (None, _) => Access::Pending,
    }
}

/// An HTTP agent configured to trust only the boat's own authority.
///
/// Built per call rather than kept around: an access request and its
/// approval poll are two calls made once in the life of an installation,
/// and a shared agent would only add state to reason about. `pub(crate)`
/// beyond this module for [`crate::resources`], which calls this on
/// every list/publish rather than once -- still built per call there
/// too, since the TLS setup this does is cheap next to the network round
/// trip it precedes, and a second implementation of the same "believe
/// only the boat's own authority" logic is a security-relevant thing to
/// risk drifting apart, not a small utility worth duplicating for its
/// own sake.
pub(crate) fn agent(trust: &Trust) -> Result<ureq::Agent, ClientError> {
    let mut tls = ureq::tls::TlsConfig::builder();
    if !trust.is_plaintext() {
        tls = tls.root_certs(ureq::tls::RootCerts::Specific(std::sync::Arc::new(
            trust.ureq_certificates(),
        )));
    }

    Ok(ureq::Agent::config_builder()
        .timeout_global(Some(TIMEOUT))
        .tls_config(tls.build())
        .build()
        .into())
}

#[cfg(test)]
mod tests {
    use super::*;

    fn answer(text: &str) -> serde_json::Value {
        serde_json::from_str(text).expect("valid json")
    }

    #[test]
    fn a_fresh_request_is_read() {
        let requested = read_requested(&answer(
            r#"{"state":"PENDING","requestId":"c5c310ed","statusCode":202}"#,
        ))
        .expect("a fresh request");
        assert_eq!(
            requested,
            Requested::New(PendingRequest {
                request_id: "c5c310ed".to_owned()
            })
        );
    }

    #[test]
    fn a_clash_is_told_from_an_ordinary_failure() {
        // The shape captured verbatim from a real server.
        let clash = read_requested(&answer(
            r#"{"state":"COMPLETED","requestId":"77980139","statusCode":400,
                "message":"A device with clientId 'client-x' has already requested access"}"#,
        ))
        .expect("read as a clash, not an error");
        assert_eq!(clash, Requested::AlreadyPending);
    }

    #[test]
    fn the_clash_requestid_is_never_offered_as_something_to_poll() {
        // It names the refused duplicate, not the original request. A
        // caller that polled it would wait on something that can never
        // resolve -- checked here by requiring AlreadyPending to carry no
        // PendingRequest at all, so there is nothing to poll by mistake.
        let clash = read_requested(&answer(
            r#"{"state":"COMPLETED","requestId":"77980139","statusCode":400,
                "message":"A device with clientId 'client-x' has already requested access"}"#,
        ))
        .expect("read as a clash, not an error");
        assert!(!matches!(clash, Requested::New(_)));
    }

    #[test]
    fn an_unrelated_400_is_still_an_error() {
        // Missing description, bad permissions value, and the like: a real
        // failure, not this one specific clash. Carries a requestId too --
        // the id of the request that was refused -- which is exactly why
        // `state` and not "is there a requestId" is what read_requested
        // checks first.
        assert!(
            read_requested(&answer(
                r#"{"state":"COMPLETED","requestId":"x","statusCode":400,
                    "message":"Invalid permissions value"}"#
            ))
            .is_err()
        );
    }

    #[test]
    fn a_fresh_request_is_pending() {
        // The shape a real server answers with, kept verbatim.
        assert_eq!(
            read_access(&answer(
                r#"{"state":"PENDING","requestId":"c5c310ed","statusCode":202}"#
            )),
            Access::Pending
        );
    }

    #[test]
    fn an_approved_request_carries_the_token() {
        let access = read_access(&answer(
            r#"{"state":"COMPLETED","requestId":"c5c310ed","statusCode":200,
                "accessRequest":{"permission":"APPROVED","token":"a.b.c"}}"#,
        ));
        assert_eq!(
            access,
            Access::Approved {
                token: "a.b.c".to_owned()
            }
        );
    }

    #[test]
    fn a_refusal_is_an_answer_and_not_an_error() {
        assert_eq!(
            read_access(&answer(
                r#"{"state":"COMPLETED","accessRequest":{"permission":"DENIED"}}"#
            )),
            Access::Denied
        );
    }

    #[test]
    fn approved_without_a_token_is_treated_as_a_refusal() {
        // Should not happen. If it does, the optimistic reading would have
        // the client connect with no credentials and fail later, somewhere
        // less obvious.
        assert_eq!(
            read_access(&answer(
                r#"{"state":"COMPLETED","accessRequest":{"permission":"APPROVED"}}"#
            )),
            Access::Denied
        );
    }

    #[test]
    fn permissions_are_spelled_the_way_the_server_spells_them() {
        assert_eq!(Permissions::ReadOnly.as_str(), "readonly");
        assert_eq!(Permissions::ReadWrite.as_str(), "readwrite");
    }
}