Developer SDK

Rust examples

Install the SDK · View source on GitHub ↗

embed/src/token.rs

rust
//! Obtaining the client JWT from the token server (EMBED_CONTRACT.md, "Obtaining the client JWT").
//! The token server is the shape of a real service's sign-in endpoint: the app posts its
//! `instance-id` to `POST /urnetwork/client-token` with its demo session as the bearer token, and
//! the server provisions or reissues the installation's client and answers its scoped client JWT.
//! [`fetch_client_jwt`] is the one function to replace with your own sign-in.

use std::fmt;

use serde_json::{Value, json};

use crate::{
    ConfigError, EXIT_CONFIG, EXIT_FAILURE,
    caps::{DataCap, parse_data_cap},
    http::{self, display_message, parse_origin},
    id::parse_id,
    state::parse_client_jwt_client_id,
};

/// The token route, after the token server origin.
pub const CLIENT_TOKEN_PATH: &str = "/urnetwork/client-token";

/// Where the app obtains its client JWT: the token server's origin and the demo session token,
/// which stands in for the developer's real sign-in. The session is a bearer secret.
#[derive(Clone, PartialEq, Eq)]
pub struct TokenServer {
    origin: String,
    session: String,
}

impl TokenServer {
    /// A token server at an HTTPS origin or explicit loopback HTTP, with a non-empty session.
    pub fn new(url: &str, session: &str) -> Result<Self, ConfigError> {
        let origin = parse_origin(url.trim(), "the token server URL")?;
        let session = session.trim();
        if session.is_empty() || session.chars().any(|c| c.is_whitespace() || c.is_control()) {
            return Err(ConfigError::new(
                "the demo session must be one token without spaces",
            ));
        }
        Ok(Self {
            origin,
            session: session.to_string(),
        })
    }

    /// The token server's origin.
    pub fn origin(&self) -> &str {
        &self.origin
    }
}

impl fmt::Debug for TokenServer {
    /// The origin only: the session is a credential.
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("TokenServer")
            .field("origin", &self.origin)
            .finish_non_exhaustive()
    }
}

/// A successful token answer.
#[derive(Clone, PartialEq, Eq)]
pub struct TokenAnswer {
    pub client_id: String,
    /// the installation's scoped client JWT: never print or log it
    pub by_client_jwt: String,
    /// the client's cap object, read by the token server; none when that read failed
    pub data_cap: Option<DataCap>,
}

impl fmt::Debug for TokenAnswer {
    /// Everything but the credential.
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("TokenAnswer")
            .field("client_id", &self.client_id)
            .field("data_cap", &self.data_cap)
            .finish_non_exhaustive()
    }
}

/// Why the token fetch did not obtain a client JWT.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum TokenError {
    /// 401 `unauthorized`, 409 `installation_limit` or `client_limit`: a restart does not fix it.
    /// The console exits with 78; a GUI shows `signed out`.
    Refused { status: u16, message: String },
    /// Unreachable, a 5xx, or an invalid answer. The console exits with 1; a GUI shows `stopped`.
    Failed(String),
}

impl TokenError {
    /// The console exit code for this answer.
    pub fn exit_code(&self) -> i32 {
        match self {
            TokenError::Refused { .. } => EXIT_CONFIG,
            TokenError::Failed(_) => EXIT_FAILURE,
        }
    }

    /// Whether a GUI shows `signed out` (otherwise `stopped`).
    pub fn signs_out(&self) -> bool {
        matches!(self, TokenError::Refused { .. })
    }
}

impl fmt::Display for TokenError {
    /// A message for the user; it never contains a credential.
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            TokenError::Refused { status, message } => {
                write!(
                    formatter,
                    "the token server refused (HTTP {status}): {message}"
                )
            }
            TokenError::Failed(message) => write!(formatter, "{message}"),
        }
    }
}

/// The `error.message` of an answer body, made safe to show.
fn answer_error_message(body: &[u8]) -> Option<String> {
    let value: Value = serde_json::from_slice(body).ok()?;
    let error = value.get("error")?;
    let message = error.get("message").and_then(Value::as_str)?;
    let code = error.get("code").and_then(Value::as_str);
    Some(match code {
        Some(code) if !code.is_empty() => {
            format!("{} ({})", display_message(message), display_message(code))
        }
        _ => display_message(message),
    })
}

/// Posts this installation's `instance-id` to the token server and checks the answer: a 200 must
/// carry a `client_id` and a `by_client_jwt` whose `client_id` claim equals it. Fetches on every
/// start, so a start reissues the client.
pub fn fetch_client_jwt(
    token_server: &TokenServer,
    instance_id: &str,
) -> Result<TokenAnswer, TokenError> {
    let body = json!({ "installation_id": instance_id }).to_string();
    let answer = http::post_json(
        &format!("{}{CLIENT_TOKEN_PATH}", token_server.origin),
        &token_server.session,
        body.as_bytes(),
    )
    .map_err(|error| {
        TokenError::Failed(format!(
            "could not reach the token server at {}: {error}",
            token_server.origin
        ))
    })?;
    match answer.status {
        200 => parse_token_answer(&answer.body),
        401 | 409 => Err(TokenError::Refused {
            status: answer.status,
            message: answer_error_message(&answer.body).unwrap_or_else(|| "no message".to_string()),
        }),
        status => Err(TokenError::Failed(
            match answer_error_message(&answer.body) {
                Some(message) => format!("the token server answered HTTP {status}: {message}"),
                None => format!("the token server answered HTTP {status}"),
            },
        )),
    }
}

/// A 200 answer's client, scoped client JWT and cap object.
pub fn parse_token_answer(body: &[u8]) -> Result<TokenAnswer, TokenError> {
    let invalid = |reason: &str| TokenError::Failed(format!("the token server's answer {reason}"));
    let value: Value = serde_json::from_slice(body).map_err(|_| invalid("is not a JSON object"))?;
    let object = value
        .as_object()
        .ok_or_else(|| invalid("is not a JSON object"))?;
    let client_id = object
        .get("client_id")
        .and_then(Value::as_str)
        .and_then(parse_id)
        .ok_or_else(|| invalid("has no valid client_id"))?;
    let by_client_jwt = object
        .get("by_client_jwt")
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|client_jwt| !client_jwt.is_empty())
        .ok_or_else(|| invalid("has no by_client_jwt"))?
        .to_string();
    let claim = parse_client_jwt_client_id(&by_client_jwt)
        .map_err(|error| invalid(&format!("carries an unusable client JWT: {error}")))?;
    if claim != client_id {
        return Err(invalid(
            "carries a client JWT for another client than its client_id",
        ));
    }
    let data_cap = object.get("data_cap").and_then(parse_data_cap);
    Ok(TokenAnswer {
        client_id,
        by_client_jwt,
        data_cap,
    })
}