docs/generated/contracts.mdgenerated from code

Reference · 7 min read

api-grants

Contracts: api-grants.

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

ruston main
1/// A grant's terms (discussion:owner/146), as the `caps` region's2/// `GrantTerms`, each optional and recorded as given: `harness` and3/// `model`, what the grantee runs, for attribution only, each at most4/// `GRANT_TERM_MAX_BYTES` (discussion:owner/178); `quota`, its5/// change quota per document, enforced only when set; and `sign_per_sec`,6/// `sign_burst`, and `gossip_per_sec`, this grant's values for the7/// grantee's buckets, the `[limits]` default when unset, the grantee being8/// metered at the largest over its live grants (discussion:owner/178). An issuer9/// may set any value. `alias` names the grantee (discussion:owner/243), for10/// display and addressing only: at most `ALIAS_MAX_BYTES` of lowercase11/// ASCII letters, digits, and `-`, starting with a letter; only the project12/// owner gives one, so any other issuer's is refused `REJECTED`13/// `out_of_scope` with an ask to the owner in `next` (discussion:owner/247); and14/// it is refused `INVALID_PARAMS`, with a free alias in `next`, when15/// another peer was ever granted it; it stays the grantee's for the16/// life of the project, revoked or not. `device` marks a device17/// certificate (discussion:owner/300).18#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]19pub struct GrantTermsParam {20    #[serde(default, skip_serializing_if = "Option::is_none")]21    pub harness: Option<String>,22    #[serde(default, skip_serializing_if = "Option::is_none")]23    pub model: Option<String>,24    #[serde(default, skip_serializing_if = "Option::is_none")]25    pub quota: Option<u64>,26    #[serde(default, skip_serializing_if = "Option::is_none")]27    pub sign_per_sec: Option<u32>,28    #[serde(default, skip_serializing_if = "Option::is_none")]29    pub sign_burst: Option<u32>,30    #[serde(default, skip_serializing_if = "Option::is_none")]31    pub gossip_per_sec: Option<u32>,32    #[serde(default, skip_serializing_if = "Option::is_none")]33    pub alias: Option<String>,34    /// A device certificate (discussion:owner/300), which `lvcs auth login` issues.35    #[serde(default, skip_serializing_if = "core::ops::Not::not")]36    pub device: bool,37    /// A device grant's name (discussion:owner/526), unique among its issuer's38    /// devices and never given again; shaped as `alias` is.39    #[serde(default, skip_serializing_if = "Option::is_none")]40    pub name: Option<String>,41    /// The grantee is a node's own instance of this plugin42    /// (discussion:owner/553), which `lvcs plugin install` and `lvcs plugin admit`43    /// set; never with `device` or `via`.44    #[serde(default, skip_serializing_if = "Option::is_none")]45    pub plugin: Option<String>,46}4748/// One capability (discussion:owner/146), as the `caps` region's `Capability`: a49/// JSON string `write`, `approve`, `delegate`, or `read` (discussion:owner/300),50/// or `{ "verb": <name> }`, a plugin's verb (discussion:owner/514): `message`51/// (messaging's) or `channel.move` (the actions plugin's, whose grant's52/// paths name the channels it moves).53#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]54#[serde(rename_all = "snake_case")]55pub enum CapabilityParam {56    Write,57    Approve,58    Delegate,59    Read,60    Verb(String),61}6263impl CapabilityParam {64    /// Messaging's verb, `message` (discussion:owner/514).65    #[must_use]66    pub fn message() -> Self {67        Self::Verb("message".to_owned())68    }69}7071/// The grantee a `grant` names to grant anyone (discussion:owner/300): only a72/// `read` grant to it means anything, letting an unauthenticated client73/// of the host node read the paths it covers (a public project).74pub const ANYONE: &str = "anyone";7576/// `grant` (discussion:owner/146): the calling peer signs a grant to77/// `grantee` (`ID_ENCODING`) for `capabilities` on `paths` (gitignore78/// syntax), on `terms` (none when omitted), starting now (the request's79/// time, in seconds). The grant's window ends `ttl_secs` after it starts,80/// and it has no expiry when `ttl_secs` is omitted; a `ttl_secs` below81/// `GRANT_TTL_MIN_SECS` is refused `INVALID_PARAMS`. A grant with a window82/// is renewed by its issuer's daemon, unattended, once half its window has83/// passed: a new grant with the same terms and a window of the same length84/// starting then, until it is revoked (`revoke`, discussion:owner/148). Refused `REJECTED` only when85/// the caller is neither the owner nor a holder of a live `delegate` grant86/// covering each capability the request names on each of its paths87/// (discussion:owner/109 and discussion:owner/146): no rule reads the terms, and any grant may88/// name any capability on any paths. Refused `INVALID_PARAMS` when89/// `harness` or `model` is longer than `GRANT_TERM_MAX_BYTES`, which every90/// node refuses in a grant (discussion:owner/178), and `REJECTED` when the caps91/// change would pass the change quota of the grant the caller issues it92/// under.93#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]94pub struct GrantParams {95    pub grantee: String,96    pub paths: Vec<String>,97    pub capabilities: Vec<CapabilityParam>,98    #[serde(default)]99    pub terms: GrantTermsParam,100    #[serde(default, skip_serializing_if = "Option::is_none")]101    pub ttl_secs: Option<u64>,102    /// A delegated grant (discussion:owner/514): the installed plugin it lets act103    /// for the caller, whose key must be `grantee`. It needs no104    /// `delegate`: any caller with a live grant issues one, and what it105    /// authorizes is no more than the caller's own grants allow.106    #[serde(default, skip_serializing_if = "Option::is_none")]107    pub via: Option<String>,108}109110/// `grant` result: the grant's id (`ID_ENCODING`) and its window in Unix111/// seconds (`not_after_s` omitted when it has no expiry).112#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]113pub struct GrantResult {114    pub grant: String,115    pub not_before_s: i64,116    #[serde(default, skip_serializing_if = "Option::is_none")]117    pub not_after_s: Option<i64>,118}119120/// `revoke` (discussion:owner/148): revoke the grant `grant` (its id, in121/// `ID_ENCODING`, the start of one, or a peer's id, alias, or id122/// prefix naming its one live grant, resolved in the daemon,123/// discussion:owner/325; several are refused with the candidates in `next`) and every unrevoked grant of its lineage, the grants124/// with the same issuer, grantee, paths, capabilities, terms, and window125/// length (its renewals, since a renewal leaves its predecessor live for126/// half a window), in one signed caps change: each revocation is127/// `/revoked/<grant id>` holding the change's own time `t`, the start of128/// the next whole second, after which no change at or past `t` is within129/// that grant; a daemon signs nothing more under a grant once its130/// revocation renders, and a revoked grant is never renewed. Refused131/// `INVALID_PARAMS` when `grant` names no grant the132/// caps document holds, and `REJECTED`, with nothing committed, unless133/// the caller is the owner, or holds a live `delegate` grant (the one a134/// caps change is signed under) and is the grant's issuer or that grant135/// also covers `delegate` on each of the grant's paths, as every node's136/// verifier requires, or when the change would pass that grant's change137/// quota (discussion:owner/178).138#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]139pub struct RevokeParams {140    pub grant: String,141}142143/// `revoke` result: the grants it revoked, in `ID_ENCODING`, sorted as144/// strings; empty when the grant and every grant of its lineage were145/// revoked already. `seen_by` and `not_seen_by` split the project's known146/// nodes (discussion:owner/326) by whether they hold every one of those147/// revocations, sorted by node id. A node keeps honouring a grant until it148/// holds its revocation, so `not_seen_by` names who still does. Just149/// after the change commits no node can hold it yet, so every known node150/// is in `not_seen_by`; `status` follows the revocation until each has it.151/// Both are empty when nothing was revoked.152#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]153pub struct RevokeResult {154    pub revoked: Vec<String>,155    #[serde(default)]156    pub seen_by: Vec<RevocationNode>,157    #[serde(default)]158    pub not_seen_by: Vec<RevocationNode>,159}160161/// A node of the project this daemon knows (discussion:owner/326): one whose caps162/// document synced with this daemon's since it started, at most163/// `REACH_NODES_MAX`. `node` is its node id, `host` the machine164/// name its inventory gave, `online` whether it syncs now, and165/// `last_seen_ms` when it last did (joined, left, or sent a caps message),166/// in Unix milliseconds by this daemon's clock.167#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]168pub struct RevocationNode {169    pub node: String,170    #[serde(default, skip_serializing_if = "Option::is_none")]171    pub host: Option<String>,172    #[serde(default)]173    pub online: bool,174    pub last_seen_ms: i64,175}176177/// `grant.holders` (discussion:owner/514): the peers whose live grants178/// hold `verb` on `scope` now, each checked as a change by that peer under179/// that grant would be (its window, revocation, and chain to the owner),180/// and the project's owner, who holds every capability. `verb` is `write`,181/// `read`, `approve`, `delegate`, or a plugin's verb (`channel.move`,182/// `secret`); `scope` is a document address or path (`.lvcs/x/actions/183/// channels/<channel>`). A grant delegated to a plugin (`via`) and a184/// grant to `anyone` name no holder: the one acts for its issuer, who is185/// counted under its own grant, and the other is no peer. `peers` is186/// sorted, has no duplicate, and never names the owner. A paired device187/// and an anonymous reader may call it too: it names peer ids and the188/// owner, no path or text (a surface's admins, ui-public-1x/8).189#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]190pub struct GrantHoldersParams {191    pub verb: String,192    pub scope: String,193}194195/// `grant.holders` result: ids in `ID_ENCODING`.196#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]197pub struct GrantHoldersResult {198    pub owner: String,199    #[serde(default)]200    pub peers: Vec<String>,201}