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