docs/generated/contracts.mdgenerated from code
Reference · 5 min read
authorize
Contracts: authorize.
Read as
Source: crates/lvcs-doc/src/kinds/caps/authorize.rs.
1/// One use of a capability to check: `signer`, holding the grant `grant`2/// (`GrantId::OWNER` for the owner, who needs none), does `need` on the3/// document at `address` at `time_s`, a change's commit time in Unix4/// seconds. For a change, `signer` and `grant` are its record's and5/// `address` what it concerns. Owner: `M3.grants`.6#[derive(Debug, Clone, Copy, PartialEq, Eq)]7pub(crate) struct Attempt<'a> {8 pub signer: &'a PeerKey,9 pub grant: &'a GrantId,10 pub address: &'a str,11 pub time_s: i64,12 pub need: &'a Capability,13}1415/// What [`chain`] found (discussion:owner/146): the signer's trust tier16/// (discussion:owner/386; `owner` for the owner, `peer` under any grant), the17/// grant's change quota (`None` for the owner and for a grant whose terms18/// name none), which the document counts in its peer's signed spans19/// (discussion:owner/70, history row 459), and the grant's rate terms. Owner: `M3.grants`.20#[derive(Debug, Clone, Copy, PartialEq, Eq)]21pub struct Terms {22 pub tier: TrustTier,23 pub quota: Option<u64>,24 pub rates: GrantRates,25}2627/// A grant's rate terms (`GrantTerms`, discussion:owner/146): each one present is28/// the grant's value for the grantee's signing or gossip bucket in place29/// of its `[limits]` default, and the daemon meters the grantee at the30/// largest over its live grants (discussion:owner/178); all absent for the owner,31/// who holds no grant, and for a grant whose terms name none. Owner:32/// `M3.grants`.33#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]34pub struct GrantRates {35 pub sign_per_sec: Option<u32>,36 pub sign_burst: Option<u32>,37 pub gossip_per_sec: Option<u32>,38}3940/// Whether the grants in `known` authorize `attempt`: the owner (the41/// signer is `known.root`'s owner and names `GrantId::OWNER`) may do42/// anything; any other signer needs `attempt.grant` in `known.grants`,43/// granted to it, with a window containing `time_s`, naming `need`, with a44/// path pattern matching `address`, and issued by the owner or by the45/// grantee of a chain link: a grant that names [`Capability::Delegate`]46/// and itself holds at `time_s` for `need` and `address`, issued by the47/// owner or another link. Every link must cover the attempt, so a48/// delegated grant is never wider than its issuer's (discussion:owner/109). No49/// rule reads a grant's terms (discussion:owner/146 and discussion:owner/147): every window is50/// `not_before_s..not_after_s` as written, any grant may name any51/// capability on any paths, and any grant naming `Delegate` is a link. A52/// grant `known.revoked` holds at `t` (discussion:owner/148) holds only before53/// `t`: its window ends at `min(not_after_s, t)`, for the attempt and for54/// every chain link, so a revoked `Delegate` link counts only for an55/// attempt before `t`.56/// Path patterns are gitignore syntax, matched against `address` and the57/// directories above it; a `!` pattern excludes what it matches wherever it sorts; an58/// `address` with a segment that is empty, `.`, or `..`, and a list with a59/// pattern that doesn't parse or a `!` line whose rest starts with `#` or60/// `!` (stripped of its `!`, it would be a comment or another `!` line,61/// and exclude nothing), match nothing. For a control document,62/// `address` is what the write concerns (discussion:owner/108, discussion:owner/109, and discussion:owner/147;63/// the document verifier maps each change to its attempts):64/// `Write` on `ALLOWLIST_ADDRESS` (discussion:owner/147) needs any valid grant:65/// its chain and windows are checked, its capabilities and paths are not.66/// No document has that address, and the document verifier names67/// only for a caps change adding `/allowlist` entries, so any valid grant68/// may add one. A change to the caps document69/// (`CAPS_ADDRESS`, `need` `Write`) needs a grant that names `Delegate`70/// (discussion:owner/109): its chain and windows are checked, its paths71/// are not; any other `need` on that address is checked like a path, as72/// is any other `need` on `ALLOWLIST_ADDRESS`'s own address. The73/// allowlist and caps rules read `address` alone, so the caller names74/// one of those addresses only for a change to that document (for75/// `ALLOWLIST_ADDRESS`, a caps change's allowlist adds, and76/// `DELEGATIONS_ADDRESS`, its delegated grants). On a channel document's77/// address (`CHANNEL_PREFIX` and a name `ChannelName::parse` takes),78/// `Approve` is decided by the address alone, like the caps rule79/// (discussion:owner/119): the chain, windows, and capability are checked,80/// its paths are not; the channel move verb (`CHANNEL_MOVE_VERB`,81/// discussion:owner/514) there, and on that channel's log document's address82/// (`LOG_PREFIX` and the name, discussion:owner/500), needs a grant naming it83/// whose paths cover the channel's name; any other `need` there is84/// checked like a path. A delegated grant (one naming a plugin in `via`,85/// discussion:owner/514) holds only when its grantee is the key of the installed86/// plugin it names (`known.plugins`) and its issuer is the owner or holds87/// a grant of its own that names no `via` and authorizes the same88/// attempt; it is never a chain link. `Approve`89/// on a file address stays a path check. That a caps change only adds entries (a `/grants/<id>`90/// entry whose issuer is the signer, an `/allowlist/<hash>` entry), never91/// deletes or overwrites one, and that only the92/// project's first change writes `/root`, is the caller's merge-time check93/// (`M3.doc`), not this one's.94/// Refusals, in95/// this order: `NoCapability` (`known.root` is unknown, a signer other96/// than the owner names `GrantId::OWNER`, the grant is unknown or another97/// signer's), `GrantExpired` (its window doesn't contain `time_s`, or it98/// was revoked at or before `time_s`),99/// `OutOfScope` (it doesn't name `need` or match `address`), and100/// `NoCapability` (no chain of links reaches the owner, as when the101/// issuer's own grant is narrower than the attempt). A chain link's path patterns are compiled102/// only once its issuer is reached, so grants that don't reach the owner103/// cost no matching.104pub(crate) fn chain(known: &GrantsKnown, attempt: &Attempt<'_>) -> Result<Terms, Denial> {