docs/generated/contracts.mdgenerated from code

Reference · 8 min read

api-auth

Contracts: api-auth.

Source: crates/lvcs-api/src/auth.rs.

ruston main
1/// The first line the daemon sends on a host node stream (discussion:owner/300):2/// the push `challenge`. A device's `hello` signs it ([`hello_message`]),3/// so its proof can't be replayed on another stream or to another host.4#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]5pub struct ChallengePush {6    /// A fresh nonce, lowercase hex.7    pub nonce: String,8    /// The host node's id.9    pub host_node: String,10}1112/// A device's proof of its key in `hello` on a host node stream13/// (discussion:owner/300): `key` (`ID_ENCODING`) and its Ed25519 `signature`14/// (lowercase hex) over [`hello_message`].15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]16pub struct DeviceProof {17    pub key: String,18    pub signature: String,19}2021/// What a device signs in `hello`: `HELLO_PROOF_CONTEXT`, the challenge's22/// `nonce`, the `host_node` id, and the `root` the `hello` names (empty23/// for none), one per line.24#[must_use]25pub fn hello_message(nonce: &str, host_node: &str, root: Option<&str>) -> String {26    format!(27        "{HELLO_PROOF_CONTEXT}\n{nonce}\n{host_node}\n{}",28        root.unwrap_or("")29    )30}3132/// What a pairing link carries after `#pair=` (discussion:owner/300), as33/// unpadded base64url of its JSON: the host node to dial, the project34/// root to name in `hello`, and the pairing's nonce for `auth.pair`.35#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]36pub struct PairLink {37    /// The link's version, 1.38    pub v: u8,39    /// The host node's id.40    pub node: String,41    /// The host node's WebRTC-direct addresses, each ending in42    /// `/p2p/<node>`.43    pub addrs: Vec<String>,44    /// The project root.45    pub root: String,46    /// The project's id, which the tracker finds the host node by47    /// (discussion:owner/327).48    pub project: String,49    /// The tracker the host node announces to, for a browser that can50    /// reach none of `addrs`; none when it announces to none.51    #[serde(default, skip_serializing_if = "Option::is_none")]52    pub tracker: Option<String>,53    /// The STUN servers the host node asks, which the browser asks too.54    #[serde(default, skip_serializing_if = "Vec::is_empty")]55    pub stun: Vec<String>,56    /// The host node's relayed addresses (discussion:owner/639), for a57    /// browser neither `addrs` nor the tracker's ICE reaches; none until a58    /// relay accepted its reservation.59    #[serde(default, skip_serializing_if = "Vec::is_empty")]60    pub relayed: Vec<String>,61    /// The pairing's nonce.62    pub nonce: String,63}6465/// `auth.login` (discussion:owner/300): start pairing a device for the caller.66/// The device gets `read` on `read` (every path when empty), and with67/// `write` also `message`, so it may coordinate (publish write68/// notifications, run), never edit; it signs those records itself (the push `sign`).69/// `alias` is the device's name among the caller's own devices (70/// discussion:owner/526): any person names their own, shaped as `grant`'s alias is, and a71/// name the caller gave a device before, revoked or not, is refused72/// `INVALID_PARAMS` with a free name in `next`. It is the grant's `name`73/// term, never a project alias. Answered at once with the nonce; the74/// pairing expires after `PAIRING_TTL_SECS`.75#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]76pub struct AuthLoginParams {77    #[serde(default, skip_serializing_if = "core::ops::Not::not")]78    pub write: bool,79    #[serde(default, skip_serializing_if = "Vec::is_empty")]80    pub read: Vec<String>,81    #[serde(default, skip_serializing_if = "Option::is_none")]82    pub alias: Option<String>,83}8485/// What a public link carries after `#` (discussion:owner/337 and discussion:owner/484):86/// `p=<project>@<node>,...`, the project's id and the host nodes that serve87/// it, then `&t=<tracker>` when its tracker isn't `TRACKER_URL`, and88/// `&s=<stun>,...` when its STUN servers aren't `STUN_URLS`. Anyone who opens89/// it reads the project anonymously, through that tracker, as a `read` grant90/// to anyone allows. The browser tries the nodes in order; their ids pin the91/// daemons whose signed answers it takes, so a node the link doesn't name92/// that announces the same project id serves it nothing.93#[derive(Debug, Clone, PartialEq, Eq)]94pub struct ReadLink {95    /// The project's id.96    pub project: String,97    /// The host nodes' ids, the first tried first.98    pub nodes: Vec<String>,99    /// The tracker the host nodes announce to.100    pub tracker: String,101    /// The STUN servers they ask.102    pub stun: Vec<String>,103}104105impl ReadLink {106    /// The link's fragment, without its `#`.107    #[must_use]108    pub fn fragment(&self) -> String {109        let mut out = format!("p={}@{}", self.project, self.nodes.join(","));110        if self.tracker != TRACKER_URL {111            out.push_str("&t=");112            out.push_str(&self.tracker);113        }114        if self.stun.join(",") != STUN_URLS {115            out.push_str("&s=");116            out.push_str(&self.stun.join(","));117        }118        out119    }120121    /// The link in the fragment `fragment` (with or without its `#`);122    /// `None` when it is no public link.123    #[must_use]124    pub fn parse(fragment: &str) -> Option<Self> {125        let fragment = fragment.strip_prefix('#').unwrap_or(fragment);126        let mut link: Option<Self> = None;127        let mut tracker = None;128        let mut stun = None;129        for part in fragment.split('&') {130            match part.split_once('=')? {131                ("p", value) => {132                    let (project, nodes) = value.split_once('@')?;133                    let valid = |text: &str| {134                        !text.is_empty() && text.bytes().all(|b| b.is_ascii_alphanumeric())135                    };136                    if !valid(project) || !nodes.split(',').all(valid) {137                        return None;138                    }139                    link = Some(Self {140                        project: project.to_owned(),141                        nodes: nodes.split(',').map(str::to_owned).collect(),142                        tracker: TRACKER_URL.to_owned(),143                        stun: Vec::new(),144                    });145                }146                ("t", value) => tracker = Some(value.to_owned()),147                ("s", value) => stun = Some(value.to_owned()),148                _ => {}149            }150        }151        let mut link = link?;152        if let Some(tracker) = tracker {153            link.tracker = tracker;154        }155        link.stun = stun156            .as_deref()157            .unwrap_or(STUN_URLS)158            .split(',')159            .filter(|url| !url.is_empty())160            .map(str::to_owned)161            .collect();162        Some(link)163    }164}165166/// `auth.login` result. `lvcs auth login` builds the link to open from167/// it and the host's `status`: `APP_URL`, then `#pair=` and the168/// [`PairLink`].169#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]170pub struct AuthLoginResult {171    /// The pairing's nonce, for `auth.wait`, `auth.confirm`, and the link.172    pub nonce: String,173    /// When the pairing expires, in Unix milliseconds.174    pub expires_ms: u64,175}176177/// `auth.wait` (discussion:owner/300): wait for a device to claim pairing178/// `nonce`; answered then, or refused once it expired.179#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]180pub struct AuthWaitParams {181    pub nonce: String,182}183184/// `auth.wait` result: the device that claimed the pairing.185#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]186pub struct AuthWaitResult {187    /// Its key, `ID_ENCODING`.188    pub device: String,189    /// The name it gave.190    pub name: String,191    /// The code it shows: confirm only when the two match.192    pub code: String,193    /// The name it gets among the login's person's devices unless194    /// `auth.confirm` names another: the login's `alias`, else `name`,195    /// with `-<n>` when the person named a device so before.196    #[serde(default, skip_serializing_if = "Option::is_none")]197    pub alias: Option<String>,198}199200/// `auth.confirm` (discussion:owner/300): accept (`accept`) or decline the201/// device that claimed pairing `nonce`. Accepting signs its device grant202/// as the caller, under its name among the caller's devices: the203/// login's `alias`, else this `alias` (discussion:owner/526, checked as204/// `auth.login` checks it, and a refused one leaves the pairing to205/// confirm again), else the default name; answered as `grant` is206/// (`GrantResult`). Declining answers `{}`.207#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]208pub struct AuthConfirmParams {209    pub nonce: String,210    pub accept: bool,211    #[serde(default, skip_serializing_if = "Option::is_none")]212    pub alias: Option<String>,213}214215/// `auth.pair`'s result once the device's grant renders.216#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]217pub struct AuthPaired {218    /// The device grant's id.219    pub grant: String,220    /// The device's key, `ID_ENCODING`.221    pub device: String,222    /// Its name among its person's devices (discussion:owner/526).223    #[serde(default, skip_serializing_if = "Option::is_none")]224    pub alias: Option<String>,225    /// Whether it may coordinate.226    pub write: bool,227    /// The paths it reads.228    pub read: Vec<String>,229}230231/// `auth.pair` (discussion:owner/300): the device whose `hello` proved its key232/// claims pairing `nonce`, under `name` (at most `DEVICE_NAME_MAX_BYTES`233/// of lowercase letters, digits, and `-`). Answered once the pairing is234/// confirmed, refused when it is declined or expires; meanwhile the push235/// `pairing` gives the code to show.236#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]237pub struct AuthPairParams {238    pub nonce: String,239    pub name: String,240}241242/// The push `pairing` (discussion:owner/300): the code a claiming device shows,243/// the one `lvcs auth login` shows in the terminal.244#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]245pub struct PairingPush {246    pub nonce: String,247    pub code: String,248}249250/// The push `sign` (discussion:owner/300): a write device's coordination record251/// (a gossip message) is signed by the device itself,252/// since the daemon holds no device key. The device answers with253/// `auth.sign`, its Ed25519 signature over `input` (lowercase hex bytes);254/// a record whose signature never comes is never published.255#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]256pub struct SignPush {257    /// The signing request's id, for `auth.sign`.258    pub request: u64,259    /// What to sign, lowercase hex.260    pub input: String,261}262263/// `auth.sign` (discussion:owner/300): the device's `signature` (lowercase hex)264/// over the input of the push `sign` with id `request`. Answered `{}`;265/// refused when no such request waits, or the signature isn't the266/// device's over it.267#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]268pub struct AuthSignParams {269    pub request: u64,270    pub signature: String,271}272273/// `auth.status` (discussion:owner/300): the caller's paired devices; with `all`,274/// every device anyone paired in the project, which whether the host node275/// stays on depends on (discussion:owner/526: one person's logout leaves another's276/// device paired).277#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]278pub struct AuthStatusParams {279    #[serde(default, skip_serializing_if = "std::ops::Not::not")]280    pub all: bool,281}282283/// `auth.status` result.284#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]285pub struct AuthStatusResult {286    #[serde(default)]287    pub devices: Vec<PairedDevice>,288}289290/// One live device grant the caller issued.291#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]292pub struct PairedDevice {293    /// The grant's id.294    pub grant: String,295    /// The device's key, `ID_ENCODING`.296    pub device: String,297    /// Its name among its person's devices (discussion:owner/526).298    #[serde(default, skip_serializing_if = "Option::is_none")]299    pub alias: Option<String>,300    /// The person who paired it, as the project names them, when that301    /// isn't the caller (the owner sees everyone's devices).302    #[serde(default, skip_serializing_if = "Option::is_none")]303    pub person: Option<String>,304    pub write: bool,305    pub read: Vec<String>,306    /// When it was paired, in Unix seconds.307    pub paired_s: i64,308    /// When this daemon last saw it on a host node stream since it309    /// started, in Unix milliseconds.310    #[serde(default, skip_serializing_if = "Option::is_none")]311    pub last_seen_ms: Option<u64>,312}313314/// `auth.logout` (discussion:owner/300): revoke the caller's device `device` (its315/// name among the caller's devices, or its key or a prefix of it; the316/// owner may name anyone's, as `<person>:<name>`) and every grant of its lineage, as317/// `revoke` does; its open streams close. Answered with `RevokeResult`.318#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]319pub struct AuthLogoutParams {320    pub device: String,321}