docs/generated/contracts.mdgenerated from code
Reference · 8 min read
api-auth
Contracts: api-auth.
Read as
Source: crates/lvcs-api/src/auth.rs.
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}