Skip to main content

plexus_auth_core/
grants.rs

1//! AUTH-2: **grants, roles, memberships, ceilings — and the gate** that asks
2//! them on every call.
3//!
4//! The model (AUTH-1, owner 2026-10-10: "every method should be its own grant
5//! inherently and require a role to have it explicitly listed if not admin
6//! role"):
7//!
8//! - A [`Grant`] is the right to call one method: `<activation>.<method>`
9//!   (`tickets.set_status`). Inherent — every method has exactly one and
10//!   nothing declares it.
11//! - A role is a named, explicit list of grants ([`GrantSet::Listed`]); the
12//!   built-in [`ADMIN`] role alone holds every grant ([`GrantSet::All`]).
13//!   [`RoleTable`] is an in-memory [`Roles`] in which a role may list
14//!   another role (inclusion), flattened as it is defined.
15//! - A [`Membership`] says a principal holds a role on a scope
16//!   ([`ScopeRef::Named`]) or everywhere ([`ScopeRef::Everywhere`], `*`).
17//! - A *target* is the param that locates the resource a call acts on; the
18//!   service's [`Resolve`] maps its value to the scopes it lives in,
19//!   innermost first (`MENGER-12` → `[MENGER, *]`).
20//! - A [`Ceiling`] is a session's upper bound (IDENTITY-40): `role@SCOPE` or
21//!   `grant@SCOPE` entries. A session may carry several layers; every layer
22//!   must allow a check, as the memberships must.
23//!
24//! [`Gate::check`] answers one call: allowed — with the [`Reach`] the method
25//! answers from — or a [`Refusal`] that names what was needed. Everything is
26//! answered from memory: the three service traits are synchronous and must
27//! not do I/O.
28//!
29//! # Relation to R-5's [`ScopeRegistry`](crate::ScopeRegistry)
30//!
31//! R-5's registry maps *token-claimed roles* to dotted capability scopes and
32//! knows nothing of where a role is held. The grant model keeps its words —
33//! a grant is exactly R-5's implicit `<activation>.<method>` scope, and
34//! [`RoleName`] is the same type — and adds the *where*: memberships on
35//! scopes, targets resolved through a chain, ceilings. Both gates can be
36//! configured on one hub; a hub with neither dispatches as before.
37
38use std::collections::{BTreeMap, BTreeSet};
39use std::fmt;
40use std::sync::Arc;
41
42use serde::{Deserialize, Deserializer, Serialize, Serializer};
43
44use crate::audit::RoleName;
45use crate::auth::AuthContext;
46use crate::identity::Principal;
47
48/// The built-in role that holds every grant. No other role holds anything it
49/// does not list.
50pub const ADMIN: &str = "admin";
51
52/// The metadata key a session's ceiling rides under (IDENTITY-42's
53/// `menger_session` sessions write it): either a list of `role@SCOPE` /
54/// `grant@SCOPE` strings (one layer) or a list of such lists (layers, every
55/// one of which must allow a check).
56pub const CEILING_KEY: &str = "ceiling";
57
58// ---------------------------------------------------------------------------
59// Grant
60// ---------------------------------------------------------------------------
61
62/// The right to call one method: `<activation>.<method>`, e.g.
63/// `tickets.set_status`. Every method has exactly one; nothing declares it.
64#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
65#[serde(transparent)]
66pub struct Grant(String);
67
68impl Grant {
69    /// Wrap a dotted method path as a grant. Unvalidated, as wire-decoded
70    /// values are.
71    pub fn new(path: impl Into<String>) -> Self {
72        Self(path.into())
73    }
74
75    /// The grant of `method` on `activation`: `<activation>.<method>`.
76    pub fn of(activation: &str, method: &str) -> Self {
77        Self(format!("{activation}.{method}"))
78    }
79
80    /// The dotted path.
81    pub fn as_str(&self) -> &str {
82        &self.0
83    }
84}
85
86impl fmt::Display for Grant {
87    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
88        f.write_str(&self.0)
89    }
90}
91
92// ---------------------------------------------------------------------------
93// ScopeRef
94// ---------------------------------------------------------------------------
95
96/// Where a role is held: everywhere (`*`) or one named scope (`MENGER`).
97/// What a name means — a shortcode, a tenant, a project — is the service's;
98/// the gate only compares names and asks [`Resolve::chain`] how they nest.
99///
100/// On the wire, a plain string: `"*"` or the name.
101#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
102pub enum ScopeRef {
103    /// `*`: every scope.
104    Everywhere,
105    /// One named scope, and whatever the service nests under it.
106    Named(String),
107}
108
109impl ScopeRef {
110    /// `"*"` → [`ScopeRef::Everywhere`]; anything else (trimmed) → named.
111    pub fn parse(text: &str) -> Self {
112        match text.trim() {
113            "*" => Self::Everywhere,
114            other => Self::Named(other.to_string()),
115        }
116    }
117
118    /// A named scope.
119    pub fn named(name: impl Into<String>) -> Self {
120        Self::Named(name.into())
121    }
122
123    /// `"*"` or the name.
124    pub fn as_str(&self) -> &str {
125        match self {
126            Self::Everywhere => "*",
127            Self::Named(n) => n,
128        }
129    }
130
131    /// Whether this is `*`.
132    pub fn is_everywhere(&self) -> bool {
133        matches!(self, Self::Everywhere)
134    }
135}
136
137impl fmt::Display for ScopeRef {
138    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
139        f.write_str(self.as_str())
140    }
141}
142
143impl Serialize for ScopeRef {
144    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
145        s.serialize_str(self.as_str())
146    }
147}
148
149impl<'de> Deserialize<'de> for ScopeRef {
150    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
151        let s = String::deserialize(d)?;
152        Ok(Self::parse(&s))
153    }
154}
155
156// ---------------------------------------------------------------------------
157// GrantSet, RoleOrGrant, Membership, Ceiling
158// ---------------------------------------------------------------------------
159
160/// What a role holds: every grant ([`ADMIN`]) or exactly those it lists.
161#[derive(Debug, Clone, PartialEq, Eq)]
162pub enum GrantSet {
163    /// Every grant — the admin role, and only it by default.
164    All,
165    /// Exactly these grants.
166    Listed(BTreeSet<Grant>),
167}
168
169impl GrantSet {
170    /// Whether the set holds `grant`.
171    pub fn contains(&self, grant: &Grant) -> bool {
172        match self {
173            Self::All => true,
174            Self::Listed(set) => set.contains(grant),
175        }
176    }
177
178    /// A listed set from anything that names grants.
179    pub fn listed<I, G>(grants: I) -> Self
180    where
181        I: IntoIterator<Item = G>,
182        G: Into<String>,
183    {
184        Self::Listed(grants.into_iter().map(|g| Grant::new(g)).collect())
185    }
186}
187
188/// One ceiling entry's left side: a role (`editor`) or a single grant
189/// (`tickets.get`). A dotted name is a grant; a bare one is a role.
190#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
191pub enum RoleOrGrant {
192    Role(RoleName),
193    Grant(Grant),
194}
195
196impl RoleOrGrant {
197    /// A dotted name is a grant, a bare one a role.
198    pub fn parse(text: &str) -> Self {
199        let t = text.trim();
200        if t.contains('.') {
201            Self::Grant(Grant::new(t))
202        } else {
203            Self::Role(RoleName::new(t))
204        }
205    }
206}
207
208impl fmt::Display for RoleOrGrant {
209    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
210        match self {
211            Self::Role(r) => write!(f, "{r}"),
212            Self::Grant(g) => write!(f, "{g}"),
213        }
214    }
215}
216
217/// A principal holds a role on a scope: `key:ac79… is editor on MENGER`.
218#[derive(Debug, Clone, PartialEq, Eq)]
219pub struct Membership {
220    pub principal: Principal,
221    pub role: RoleName,
222    pub scope: ScopeRef,
223}
224
225/// A session's upper bound (IDENTITY-40): `(role or grant, scope)` entries,
226/// spelled `editor@MENGER-12`, `tickets.get@*`. A check passes a ceiling
227/// when some entry's scope is in the target's chain and the entry allows the
228/// grant (the grant itself, or a role listing it).
229#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
230pub struct Ceiling(pub Vec<(RoleOrGrant, ScopeRef)>);
231
232/// Why a ceiling could not be read.
233#[derive(Debug, Clone, PartialEq, Eq)]
234pub struct CeilingError(pub String);
235
236impl fmt::Display for CeilingError {
237    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
238        f.write_str(&self.0)
239    }
240}
241
242impl std::error::Error for CeilingError {}
243
244impl Ceiling {
245    /// One `role@SCOPE` or `grant@SCOPE` entry.
246    pub fn entry(text: &str) -> Result<(RoleOrGrant, ScopeRef), CeilingError> {
247        let (left, scope) = text
248            .trim()
249            .split_once('@')
250            .ok_or_else(|| CeilingError(format!("`{}` is not role@SCOPE or grant@SCOPE", text.trim())))?;
251        if left.trim().is_empty() || scope.trim().is_empty() {
252            return Err(CeilingError(format!("`{}` is not role@SCOPE or grant@SCOPE", text.trim())));
253        }
254        Ok((RoleOrGrant::parse(left), ScopeRef::parse(scope)))
255    }
256
257    /// A ceiling from its entries' text.
258    pub fn parse<I, S>(entries: I) -> Result<Self, CeilingError>
259    where
260        I: IntoIterator<Item = S>,
261        S: AsRef<str>,
262    {
263        entries
264            .into_iter()
265            .map(|e| Self::entry(e.as_ref()))
266            .collect::<Result<Vec<_>, _>>()
267            .map(Ceiling)
268    }
269
270    /// The entries as the wire says them: `role@SCOPE` each.
271    pub fn text(&self) -> Vec<String> {
272        self.0.iter().map(|(rg, s)| format!("{rg}@{s}")).collect()
273    }
274
275    /// The ceilings an identity's metadata carries under [`CEILING_KEY`]:
276    /// none → `[]`; a list of strings → one layer; a list of lists → one
277    /// layer each. Anything else is an error, and a caller whose ceiling
278    /// cannot be read must be refused, never widened.
279    pub fn layers_of(ctx: &AuthContext) -> Result<Vec<Ceiling>, CeilingError> {
280        let Some(v) = ctx.metadata.get(CEILING_KEY) else {
281            return Ok(Vec::new());
282        };
283        let unreadable = || CeilingError("this session's ceiling cannot be read: sign in again".into());
284        let items = v.as_array().ok_or_else(unreadable)?;
285        if items.iter().all(|i| i.is_string()) {
286            let texts: Vec<&str> = items.iter().filter_map(|i| i.as_str()).collect();
287            return Ok(vec![Self::parse(texts).map_err(|_| unreadable())?]);
288        }
289        items
290            .iter()
291            .map(|layer| {
292                let entries = layer.as_array().ok_or_else(unreadable)?;
293                let texts = entries
294                    .iter()
295                    .map(|e| e.as_str().ok_or_else(unreadable))
296                    .collect::<Result<Vec<_>, _>>()?;
297                Self::parse(texts).map_err(|_| unreadable())
298            })
299            .collect()
300    }
301}
302
303/// PERF-15: everything [`Gate::held_on`] reads of one signed-in caller,
304/// besides the grants generation — what its principal holds (each
305/// membership's role and scope, as a set) and its session's ceiling layers.
306/// Two callers with equal fingerprints hold the same grants on the same
307/// scopes, whoever they are: at one generation the gate answers them alike.
308/// So a service keeps what a caller may see (its view, AUTH-4) by it —
309/// one entry shared by every caller holding the same, dropped when the
310/// generation moves. Compared whole, never by a digest: two fingerprints are
311/// one key only when they are equal. [`Gate::fingerprint`] takes one,
312/// [`Gate::held_on_by`] answers from it.
313#[derive(Debug, Clone, PartialEq, Eq, Hash)]
314pub struct Fingerprint {
315    /// (role, scope) of each membership, sorted, each once.
316    held: Vec<(RoleName, ScopeRef)>,
317    /// The session's ceiling, as [`Ceiling::layers_of`] reads it (an
318    /// unreadable one is one empty layer, as the gate reads it).
319    layers: Vec<Ceiling>,
320}
321
322// ---------------------------------------------------------------------------
323// What a service supplies
324// ---------------------------------------------------------------------------
325
326/// Who holds which role where (menger: its members table, cached). Answered
327/// from memory: no I/O on a call.
328pub trait Memberships: Send + Sync {
329    fn held(&self, who: &Principal) -> Vec<Membership>;
330
331    /// What `who` holds of its own — without a membership the service
332    /// gives every signed-in principal (menger's `everyone` grant). It
333    /// decides whether `who` is still waiting for an admin (`auth.waiting`,
334    /// `auth.signup`); the gate reads [`Memberships::held`]. The default is
335    /// `held`: a service with no such grant has nothing to leave out.
336    fn own_held(&self, who: &Principal) -> Vec<Membership> {
337        self.held(who)
338    }
339}
340
341/// Role → grants (defaults declared in code, edits as data). Answered from
342/// memory. [`ADMIN`] holds every grant whatever this answers.
343pub trait Roles: Send + Sync {
344    /// What `role` holds; `None` for a role this service does not know
345    /// (it holds nothing).
346    fn grants(&self, role: &RoleName) -> Option<GrantSet>;
347
348    /// Every role this service knows, so a refusal can name the roles that
349    /// list a grant. The default knows none (a refusal then names only
350    /// [`ADMIN`]).
351    fn names(&self) -> Vec<RoleName> {
352        Vec::new()
353    }
354}
355
356/// Where a target lives. Answered from memory.
357pub trait Resolve: Send + Sync {
358    /// The scopes a target lives in, innermost first, ending in
359    /// [`ScopeRef::Everywhere`]: `"MENGER-12"` → `[MENGER-12, MENGER, *]`
360    /// (or, for a service whose memberships are per shortcode,
361    /// `[MENGER, *]`). `None`: the value locates nothing — the call is
362    /// refused.
363    ///
364    /// The gate also asks it about **scope names** (a membership's or a
365    /// ceiling's): `chain("MENGER")` → `[MENGER, PLEXUS, *]`, to tell which
366    /// of two scopes lies within the other when it narrows a reach by a
367    /// ceiling. A service that cannot answer for a name returns `None`, and
368    /// two different names are then taken as disjoint.
369    fn chain(&self, target: &str) -> Option<Vec<ScopeRef>>;
370}
371
372// ---------------------------------------------------------------------------
373// RoleTable — an in-memory Roles with inclusion
374// ---------------------------------------------------------------------------
375
376/// Why [`RoleTable::define`] refused a role.
377#[derive(Debug, Clone, PartialEq, Eq)]
378pub enum RoleTableError {
379    /// An entry named a role that is not (yet) defined. A role may only
380    /// include roles defined before it, which is what keeps inclusion
381    /// acyclic.
382    UnknownRole { role: String, includes: String },
383}
384
385impl fmt::Display for RoleTableError {
386    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
387        match self {
388            Self::UnknownRole { role, includes } => write!(
389                f,
390                "role {role} includes {includes}, which is not defined before it"
391            ),
392        }
393    }
394}
395
396impl std::error::Error for RoleTableError {}
397
398/// An in-memory [`Roles`]: each role an explicit list of grants, where an
399/// entry may also name an earlier role (inclusion, flattened when defined).
400/// [`ADMIN`] is built in.
401///
402/// ```
403/// use plexus_auth_core::grants::{Grant, RoleTable, Roles};
404/// use plexus_auth_core::RoleName;
405///
406/// let roles = RoleTable::new()
407///     .define("viewer", ["tickets.get", "tickets.list"]).unwrap()
408///     .define("editor", ["viewer", "tickets.set_status"]).unwrap();
409/// let editor = roles.grants(&RoleName::new("editor")).unwrap();
410/// assert!(editor.contains(&Grant::new("tickets.get")));
411/// ```
412#[derive(Debug, Clone, Default)]
413pub struct RoleTable {
414    roles: BTreeMap<RoleName, GrantSet>,
415}
416
417impl RoleTable {
418    /// The table with only the built-in [`ADMIN`].
419    pub fn new() -> Self {
420        Self::default()
421    }
422
423    /// Define (or extend) `role`: each entry a grant (dotted) or an earlier
424    /// role (bare), whose grants are included. Defining a role again adds to
425    /// it, which is how several activations' defaults for one role name
426    /// merge.
427    pub fn define<I, S>(mut self, role: &str, entries: I) -> Result<Self, RoleTableError>
428    where
429        I: IntoIterator<Item = S>,
430        S: AsRef<str>,
431    {
432        let name = RoleName::new(role);
433        let mut set = match self.roles.remove(&name) {
434            Some(GrantSet::Listed(s)) => s,
435            Some(GrantSet::All) => {
436                self.roles.insert(name, GrantSet::All);
437                return Ok(self);
438            }
439            None => BTreeSet::new(),
440        };
441        let mut all = name.as_str() == ADMIN;
442        for entry in entries {
443            let e = entry.as_ref().trim();
444            if e.contains('.') {
445                set.insert(Grant::new(e));
446                continue;
447            }
448            if e == ADMIN {
449                all = true;
450                continue;
451            }
452            match self.roles.get(&RoleName::new(e)) {
453                Some(GrantSet::All) => all = true,
454                Some(GrantSet::Listed(inc)) => set.extend(inc.iter().cloned()),
455                None => {
456                    return Err(RoleTableError::UnknownRole { role: role.to_string(), includes: e.to_string() })
457                }
458            }
459        }
460        self.roles.insert(name, if all { GrantSet::All } else { GrantSet::Listed(set) });
461        Ok(self)
462    }
463
464    /// Replace `role`'s grants outright (an admin's edit: the store wins).
465    pub fn set(&mut self, role: &str, grants: GrantSet) {
466        self.roles.insert(RoleName::new(role), grants);
467    }
468
469    /// A table from already-flat lists (`role → [grant, …]`), as a schema's
470    /// `roles` carries them; lists for one role name merge.
471    pub fn from_lists<'a, I, G>(lists: I) -> Self
472    where
473        I: IntoIterator<Item = (&'a str, G)>,
474        G: IntoIterator,
475        G::Item: AsRef<str>,
476    {
477        let mut table = Self::new();
478        for (role, grants) in lists {
479            let name = RoleName::new(role);
480            let grants: Vec<Grant> = grants.into_iter().map(|g| Grant::new(g.as_ref().trim())).collect();
481            match table.roles.entry(name) {
482                std::collections::btree_map::Entry::Occupied(mut o) => {
483                    if let GrantSet::Listed(s) = o.get_mut() {
484                        s.extend(grants);
485                    }
486                }
487                std::collections::btree_map::Entry::Vacant(v) => {
488                    v.insert(if role == ADMIN { GrantSet::All } else { GrantSet::Listed(grants.into_iter().collect()) });
489                }
490            }
491        }
492        table
493    }
494}
495
496impl Roles for RoleTable {
497    fn grants(&self, role: &RoleName) -> Option<GrantSet> {
498        if role.as_str() == ADMIN {
499            return Some(GrantSet::All);
500        }
501        self.roles.get(role).cloned()
502    }
503
504    fn names(&self) -> Vec<RoleName> {
505        self.roles.keys().cloned().collect()
506    }
507}
508
509// ---------------------------------------------------------------------------
510// Refusal
511// ---------------------------------------------------------------------------
512
513/// Why the gate refused a call.
514#[derive(Debug, Clone, PartialEq, Eq)]
515pub enum Refusal {
516    /// No principal: only `public` methods are reachable anonymously.
517    Unauthenticated,
518    /// The caller does not hold `grant` on `scope` (within its ceiling).
519    MissingGrant {
520        /// The grant the call needed.
521        grant: Grant,
522        /// Where it was needed: the target's innermost scope, or `*` for a
523        /// method without a target (held anywhere would have done).
524        scope: ScopeRef,
525        /// The roles that list the grant ([`ADMIN`] last).
526        roles: Vec<RoleName>,
527        /// Where the caller does hold it (within its ceiling).
528        held_on: Vec<ScopeRef>,
529    },
530    /// AUTH-11: the caller signed in, but that sign-in no longer stands
531    /// (signed out, expired, revoked) — it proves no one.
532    Ended {
533        /// Why, in words for the caller ("you have signed out: sign in
534        /// again").
535        reason: String,
536    },
537}
538
539impl fmt::Display for Refusal {
540    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
541        match self {
542            Self::Unauthenticated => f.write_str("sign in first"),
543            Self::Ended { reason } => f.write_str(reason),
544            Self::MissingGrant { grant, scope, .. } => write!(f, "needs {grant} on {scope}"),
545        }
546    }
547}
548
549impl std::error::Error for Refusal {}
550
551// ---------------------------------------------------------------------------
552// Reach
553// ---------------------------------------------------------------------------
554
555/// Where a call may act: the scopes the caller holds the method's grant on
556/// (within its ceiling), handed to the method beside `auth`. A read without a
557/// target (`list`, `watch`) answers only from these.
558///
559/// A reach is **live** when it came from a gate: [`Reach::allows`] and
560/// [`Reach::current`] ask the gate again, as memberships, roles and the
561/// ceiling stand *now* — so a stream checks each event (IDENTITY-37: a role
562/// revoked reaches an open stream at its next event). A hub without a gate
563/// hands every method [`Reach::everywhere`], which allows everything.
564#[derive(Clone)]
565pub struct Reach {
566    /// PERF.115-49: borrowed for the two constant answers (everywhere,
567    /// nowhere), so a service without a gate allocates nothing for them.
568    held_on: std::borrow::Cow<'static, [ScopeRef]>,
569    live: Option<Live>,
570}
571
572#[derive(Clone)]
573struct Live {
574    gate: Gate,
575    caller: Option<AuthContext>,
576    grant: Grant,
577    /// KEEL-31: the reach of a method that acts on the whole service — asked
578    /// again by [`Gate::check_everywhere`], so it lasts only while the grant
579    /// is held on `*`.
580    everywhere: bool,
581}
582
583impl Live {
584    /// The gate's answer now, by the rule this reach was given by.
585    fn now(&self) -> Result<Reach, Refusal> {
586        match self.everywhere {
587            true => self.gate.check_everywhere(self.caller.as_ref(), &self.grant),
588            false => self.gate.check(self.caller.as_ref(), &self.grant, None),
589        }
590    }
591}
592
593impl fmt::Debug for Reach {
594    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
595        f.debug_struct("Reach")
596            .field("held_on", &self.held_on)
597            .field("grant", &self.live.as_ref().map(|l| l.grant.as_str()))
598            .finish()
599    }
600}
601
602impl PartialEq for Reach {
603    /// Two reaches are equal when they hold the same scopes for the same
604    /// grant (the gate behind them is not compared).
605    fn eq(&self, other: &Self) -> bool {
606        self.held_on == other.held_on && self.grant() == other.grant()
607    }
608}
609
610impl Reach {
611    /// Everything — what a method receives on a hub without a gate (login
612    /// off), as today.
613    pub fn everywhere() -> Self {
614        static EVERYWHERE: [ScopeRef; 1] = [ScopeRef::Everywhere];
615        Self { held_on: std::borrow::Cow::Borrowed(&EVERYWHERE), live: None }
616    }
617
618    /// RETURNS-47: nothing — the reach of a call made for no one (a child
619    /// under the `anonymous` forward policy, or one whose caller cannot be
620    /// read). Covers and allows nothing, and names no grant.
621    pub fn nowhere() -> Self {
622        Self { held_on: std::borrow::Cow::Borrowed(&[]), live: None }
623    }
624
625    /// Whether the grant is held on `*`.
626    pub fn is_everywhere(&self) -> bool {
627        self.held_on.iter().any(ScopeRef::is_everywhere)
628    }
629
630    /// Whether the grant is held nowhere (a `public` method called by a
631    /// caller who holds no role listing it).
632    pub fn is_empty(&self) -> bool {
633        self.held_on.is_empty()
634    }
635
636    /// The scopes the grant is held on; `[*]` when everywhere.
637    pub fn held_on(&self) -> &[ScopeRef] {
638        &self.held_on
639    }
640
641    /// PERF.115-49: the caller this reach was decided for — the context the
642    /// gate was asked about, which it keeps to ask again; `None` for an
643    /// anonymous caller and for a reach no gate made ([`Reach::everywhere`],
644    /// [`Reach::nowhere`]). Lets a holder of the reach read that caller
645    /// rather than keep a second copy of it.
646    pub fn caller(&self) -> Option<&AuthContext> {
647        self.live.as_ref().and_then(|l| l.caller.as_ref())
648    }
649
650    /// The grant this reach is for; `None` on a service without a gate.
651    pub fn grant(&self) -> Option<&Grant> {
652        self.live.as_ref().map(|l| &l.grant)
653    }
654
655    /// POLYGLOT-5: the grants generation of the gate this reach came from
656    /// (BIDIR-8) — a call held open elsewhere (a child service's stream)
657    /// asks [`Reach::current`] again only when it moved. `None` without a
658    /// gate.
659    pub fn generation(&self) -> Option<&GrantsGeneration> {
660        self.live.as_ref().map(|l| l.gate.generation())
661    }
662
663    /// Whether the call may act on `target` — asked of the gate as it
664    /// stands now. Without a gate: always. KEEL-31: a whole-service
665    /// method's reach allows a target only while the grant is held on `*`.
666    pub fn allows(&self, target: &str) -> bool {
667        match &self.live {
668            None => self.is_everywhere(),
669            Some(l) if l.everywhere => l.now().is_ok(),
670            Some(l) => l.gate.check(l.caller.as_ref(), &l.grant, Some(target)).is_ok(),
671        }
672    }
673
674    /// The reach as it stands now: `None` once the grant is held nowhere (a
675    /// stream should end). Without a gate: unchanged.
676    pub fn current(&self) -> Option<Reach> {
677        match &self.live {
678            None => Some(self.clone()),
679            Some(l) => l.now().ok(),
680        }
681    }
682
683    /// FRAME-5: [`Reach::current`] with the gate's refusal kept — `Err`
684    /// says why the grant is held nowhere now: [`Refusal::Ended`] when the
685    /// sign-in no longer stands (signed out, expired, revoked session),
686    /// [`Refusal::MissingGrant`] when the grants moved away,
687    /// [`Refusal::Unauthenticated`] when the caller proves no one. A held
688    /// open call that must say *why* it ends (a watch's typed reason) asks
689    /// this; one that only needs to know whether asks `current`. Without a
690    /// gate: unchanged.
691    pub fn recheck(&self) -> Result<Reach, Refusal> {
692        match &self.live {
693            None => Ok(self.clone()),
694            Some(l) => l.now(),
695        }
696    }
697
698    /// Whether the reach covers a target whose chain is `chain` (as
699    /// [`Resolve::chain`] gives it), by this snapshot — no new question to
700    /// the gate. Prefer [`Reach::allows`] where the answer must be current.
701    pub fn covers(&self, chain: &[ScopeRef]) -> bool {
702        self.is_everywhere() || self.held_on.iter().any(|s| chain.contains(s))
703    }
704}
705
706// ---------------------------------------------------------------------------
707// Gate
708// ---------------------------------------------------------------------------
709
710/// AUTH-11: whether a signed-in caller's sign-in still stands — the
711/// service's session table, asked by [`Gate::check`] on every call (and so
712/// on every [`Reach::allows`] / [`Reach::current`] a stream makes). A
713/// signed-out or revoked session proves no one, whatever its principal
714/// holds. Memory only, like the other service traits.
715pub trait Liveness: Send + Sync {
716    /// `Err`: why the sign-in no longer stands, in words for the caller.
717    fn alive(&self, caller: &AuthContext) -> Result<(), String>;
718}
719
720struct GateInner {
721    memberships: Arc<dyn Memberships>,
722    roles: Arc<dyn Roles>,
723    resolve: Arc<dyn Resolve>,
724    liveness: Option<Arc<dyn Liveness>>,
725    generation: GrantsGeneration,
726}
727
728/// BIDIR-8: what moved the grants generation ([`Gate::moved`]) — every
729/// write that could change an answer the gate gave.
730#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
731pub enum GrantsMove {
732    /// A membership added.
733    Grant,
734    /// A membership removed.
735    Revoke,
736    /// A role's grants edited.
737    RoleEdit,
738    /// A principal added to a team (it holds the team's grants).
739    TeamAdd,
740    /// A principal removed from a team.
741    TeamRemove,
742    /// A sign-in ended: signed out, or its session revoked.
743    SignOut,
744}
745
746/// BIDIR-8 (BIDIR-5's finding): the **grants generation** — a count every
747/// write that could change one of the gate's answers moves
748/// ([`GrantsMove`]). It is the gate's: whoever holds an answer across time
749/// (a duplex call's caller, a watch) records the generation it was decided
750/// at and asks the gate again only when it has moved — once per move, never
751/// per item. Cheap to clone (two `Arc`s, one count); a read is one atomic
752/// load; a move wakes every [`subscribe`](GrantsGeneration::subscribe)r.
753///
754/// A service shares one across its gates with [`Gate::with_generation`]
755/// (menger: the gate in front of its calls, the access layer's and the store's count are
756/// one).
757#[derive(Clone)]
758pub struct GrantsGeneration {
759    now: Arc<std::sync::atomic::AtomicU64>,
760    tx: Arc<tokio::sync::watch::Sender<u64>>,
761}
762
763impl fmt::Debug for GrantsGeneration {
764    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
765        f.debug_tuple("GrantsGeneration").field(&self.current()).finish()
766    }
767}
768
769impl Default for GrantsGeneration {
770    fn default() -> Self {
771        Self::new()
772    }
773}
774
775impl GrantsGeneration {
776    /// A count at 0.
777    pub fn new() -> Self {
778        Self { now: Arc::new(std::sync::atomic::AtomicU64::new(0)), tx: Arc::new(tokio::sync::watch::channel(0).0) }
779    }
780
781    /// Something that could change an answer moved: +1, and every
782    /// subscriber woken. Answers the generation now.
783    pub fn bump(&self) -> u64 {
784        let n = self.now.fetch_add(1, std::sync::atomic::Ordering::AcqRel) + 1;
785        self.tx.send_replace(n);
786        n
787    }
788
789    /// [`bump`](Self::bump), naming what moved (for the reader; the count
790    /// is one either way).
791    pub fn moved(&self, why: GrantsMove) -> u64 {
792        let _ = why;
793        self.bump()
794    }
795
796    /// The generation now (one atomic load).
797    pub fn current(&self) -> u64 {
798        self.now.load(std::sync::atomic::Ordering::Acquire)
799    }
800
801    /// At least `n` — a service that counted before it shared this handle
802    /// carries its count over. Never back: a smaller `n` changes nothing.
803    pub fn raise_to(&self, n: u64) {
804        let was = self.now.fetch_max(n, std::sync::atomic::Ordering::AcqRel);
805        if n > was {
806            self.tx.send_replace(self.current());
807        }
808    }
809
810    /// What wakes a holder when the generation moves.
811    pub fn subscribe(&self) -> tokio::sync::watch::Receiver<u64> {
812        self.tx.subscribe()
813    }
814}
815
816/// The one rule in front of every call: the method's grant, held through a
817/// role on the target's scope, within the session's ceiling. Default deny.
818/// Cheap to clone (one `Arc`); cheap to ask (memory only), so a stream may
819/// ask per event.
820#[derive(Clone)]
821pub struct Gate {
822    inner: Arc<GateInner>,
823}
824
825impl fmt::Debug for Gate {
826    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
827        f.write_str("Gate")
828    }
829}
830
831impl Gate {
832    /// A gate over a service's memberships, roles and resolver.
833    pub fn new(memberships: Arc<dyn Memberships>, roles: Arc<dyn Roles>, resolve: Arc<dyn Resolve>) -> Self {
834        Self { inner: Arc::new(GateInner { memberships, roles, resolve, liveness: None, generation: GrantsGeneration::new() }) }
835    }
836
837    /// BIDIR-8: this gate, counting its moves in `generation` — the
838    /// service's one ([`GrantsGeneration`]), shared by every gate it builds.
839    /// Without it a gate counts alone, from 0.
840    pub fn with_generation(self, generation: GrantsGeneration) -> Self {
841        let i = &self.inner;
842        Self {
843            inner: Arc::new(GateInner {
844                memberships: i.memberships.clone(),
845                roles: i.roles.clone(),
846                resolve: i.resolve.clone(),
847                liveness: i.liveness.clone(),
848                generation,
849            }),
850        }
851    }
852
853    /// BIDIR-8: the grants generation this gate's answers are decided at.
854    pub fn generation(&self) -> &GrantsGeneration {
855        &self.inner.generation
856    }
857
858    /// BIDIR-8: a write that could change this gate's answers happened
859    /// (the service wrote it — the gate keeps no memberships of its own):
860    /// the generation moves once. Answers the generation now.
861    pub fn moved(&self, why: GrantsMove) -> u64 {
862        self.inner.generation.moved(why)
863    }
864
865    /// AUTH-11: this gate, asking `liveness` whether a caller's sign-in
866    /// still stands before every check. Without it the gate still refuses
867    /// a caller past its `expires_at` stamp ([`AuthContext::expired`]).
868    pub fn with_liveness(self, liveness: Arc<dyn Liveness>) -> Self {
869        let i = &self.inner;
870        Self {
871            inner: Arc::new(GateInner {
872                memberships: i.memberships.clone(),
873                roles: i.roles.clone(),
874                resolve: i.resolve.clone(),
875                liveness: Some(liveness),
876                generation: i.generation.clone(),
877            }),
878        }
879    }
880
881    /// AUTH-11: whether `caller`'s sign-in still stands: not past its
882    /// `expires_at`, and live by the service's [`Liveness`]. An anonymous
883    /// context has no sign-in to end: `Ok`.
884    pub fn alive(&self, caller: &AuthContext) -> Result<(), String> {
885        if caller.principal().is_none() {
886            return Ok(());
887        }
888        self.alive_named(caller)
889    }
890
891    /// [`Gate::alive`] for a caller whose principal was just read (PERF.115-49:
892    /// [`Gate::check`] has it from [`Gate::caller_of`], and does not parse it
893    /// again).
894    fn alive_named(&self, caller: &AuthContext) -> Result<(), String> {
895        if caller.expired() {
896            return Err("your sign-in has expired: sign in again".into());
897        }
898        match &self.inner.liveness {
899            Some(l) => l.alive(caller),
900            None => Ok(()),
901        }
902    }
903
904    /// Whether `role` lists `grant` ([`ADMIN`] lists every grant).
905    pub fn lists(&self, role: &RoleName, grant: &Grant) -> bool {
906        role.as_str() == ADMIN || self.inner.roles.grants(role).is_some_and(|g| g.contains(grant))
907    }
908
909    /// The roles that list `grant`, [`ADMIN`] last.
910    pub fn roles_listing(&self, grant: &Grant) -> Vec<RoleName> {
911        let mut out: Vec<RoleName> = self
912            .inner
913            .roles
914            .names()
915            .into_iter()
916            .filter(|r| r.as_str() != ADMIN && self.lists(r, grant))
917            .collect();
918        out.push(RoleName::new(ADMIN));
919        out
920    }
921
922    /// Whether a ceiling entry allows `grant`.
923    fn entry_allows(&self, entry: &RoleOrGrant, grant: &Grant) -> bool {
924        match entry {
925            RoleOrGrant::Grant(g) => g == grant,
926            RoleOrGrant::Role(r) => self.lists(r, grant),
927        }
928    }
929
930    /// The caller's principal and ceiling layers; `None` when anonymous. An
931    /// unreadable ceiling becomes one empty layer — it allows nothing.
932    fn caller_of(caller: Option<&AuthContext>) -> Option<(Principal, Vec<Ceiling>)> {
933        let ctx = caller?;
934        let principal = ctx.principal()?;
935        let layers = Ceiling::layers_of(ctx).unwrap_or_else(|_| vec![Ceiling::default()]);
936        Some((principal, layers))
937    }
938
939    /// Whether `inner` lies within `outer` (or is it).
940    fn within(&self, inner: &ScopeRef, outer: &ScopeRef) -> bool {
941        if outer.is_everywhere() || inner == outer {
942            return true;
943        }
944        match inner {
945            ScopeRef::Everywhere => false,
946            ScopeRef::Named(name) => self.inner.resolve.chain(name).is_some_and(|c| c.contains(outer)),
947        }
948    }
949
950    /// The scopes both `a` and `b` reach: where one lies within the other,
951    /// the inner one.
952    fn meet(&self, a: Vec<ScopeRef>, b: Vec<ScopeRef>) -> Vec<ScopeRef> {
953        if a.iter().any(ScopeRef::is_everywhere) {
954            return b;
955        }
956        if b.iter().any(ScopeRef::is_everywhere) {
957            return a;
958        }
959        let mut out = BTreeSet::new();
960        for x in &a {
961            for y in &b {
962                if self.within(x, y) {
963                    out.insert(x.clone());
964                } else if self.within(y, x) {
965                    out.insert(y.clone());
966                }
967            }
968        }
969        out.into_iter().collect()
970    }
971
972    /// Collapse to `[*]` when `*` is among them; dedupe, ordered.
973    fn normal(scopes: impl IntoIterator<Item = ScopeRef>) -> Vec<ScopeRef> {
974        let set: BTreeSet<ScopeRef> = scopes.into_iter().collect();
975        if set.contains(&ScopeRef::Everywhere) {
976            vec![ScopeRef::Everywhere]
977        } else {
978            set.into_iter().collect()
979        }
980    }
981
982    fn held_on_for(&self, principal: &Principal, layers: &[Ceiling], grant: &Grant) -> Vec<ScopeRef> {
983        let held = self.inner.memberships.held(principal);
984        self.held_on_in(held.iter().map(|m| (&m.role, &m.scope)), layers, grant)
985    }
986
987    /// Where `held` (role, scope pairs) holds `grant` within `layers`: what
988    /// [`Gate::held_on`] answers from the memberships and
989    /// [`Gate::held_on_by`] from a [`Fingerprint`] — one rule.
990    fn held_on_in<'a>(
991        &self,
992        held: impl Iterator<Item = (&'a RoleName, &'a ScopeRef)>,
993        layers: &[Ceiling],
994        grant: &Grant,
995    ) -> Vec<ScopeRef> {
996        let mut acc = Self::normal(held.filter(|(role, _)| self.lists(role, grant)).map(|(_, scope)| scope.clone()));
997        for layer in layers {
998            if acc.is_empty() {
999                break;
1000            }
1001            let allowed = Self::normal(
1002                layer.0.iter().filter(|(rg, _)| self.entry_allows(rg, grant)).map(|(_, s)| s.clone()),
1003            );
1004            acc = self.meet(acc, allowed);
1005        }
1006        acc
1007    }
1008
1009    /// Where the caller holds `grant`, within its ceiling: `[*]` when
1010    /// everywhere, `[]` when nowhere (and for an anonymous caller). What a
1011    /// method without a target answers from.
1012    pub fn held_on(&self, caller: &AuthContext, grant: &Grant) -> Vec<ScopeRef> {
1013        match Self::caller_of(Some(caller)) {
1014            Some((p, layers)) => self.held_on_for(&p, &layers, grant),
1015            None => Vec::new(),
1016        }
1017    }
1018
1019    /// PERF-15: what this gate's answers about `caller` read, besides the
1020    /// grants generation — its principal's memberships and its session's
1021    /// ceiling ([`Fingerprint`]); `None` when it is anonymous. The
1022    /// memberships are read now, from memory.
1023    pub fn fingerprint(&self, caller: &AuthContext) -> Option<Fingerprint> {
1024        let (principal, layers) = Self::caller_of(Some(caller))?;
1025        let mut held: Vec<(RoleName, ScopeRef)> =
1026            self.inner.memberships.held(&principal).into_iter().map(|m| (m.role, m.scope)).collect();
1027        held.sort();
1028        held.dedup();
1029        Some(Fingerprint { held, layers })
1030    }
1031
1032    /// PERF-15: [`Gate::held_on`] for whoever has `who` — read from the
1033    /// fingerprint instead of the memberships, by the same rule, so a view
1034    /// built from it is exactly the one built from any caller it was taken
1035    /// of.
1036    pub fn held_on_by(&self, who: &Fingerprint, grant: &Grant) -> Vec<ScopeRef> {
1037        self.held_on_in(who.held.iter().map(|(r, s)| (r, s)), &who.layers, grant)
1038    }
1039
1040    /// Allowed when the grant is listed by a role held on a scope in the
1041    /// target's chain — or anywhere, for a call with no target — and every
1042    /// ceiling layer allows it the same way. The [`Reach`] is live (it asks
1043    /// this gate again on [`Reach::allows`] / [`Reach::current`]).
1044    ///
1045    /// AUTH-11: first, the caller's sign-in must still stand
1046    /// ([`Gate::alive`]) — a signed-out session holds nothing, so a socket
1047    /// that signed out cannot go on to call `auth.grant`.
1048    pub fn check(&self, caller: Option<&AuthContext>, grant: &Grant, target: Option<&str>) -> Result<Reach, Refusal> {
1049        let Some((principal, layers)) = Self::caller_of(caller) else {
1050            return Err(Refusal::Unauthenticated);
1051        };
1052        if let Some(ctx) = caller {
1053            self.alive_named(ctx).map_err(|reason| Refusal::Ended { reason })?;
1054        }
1055        let held_on = self.held_on_for(&principal, &layers, grant);
1056        let (allowed, scope) = match target {
1057            None => (!held_on.is_empty(), ScopeRef::Everywhere),
1058            Some(t) => match self.inner.resolve.chain(t) {
1059                None => (false, ScopeRef::named(t)),
1060                Some(chain) => {
1061                    let in_chain = |s: &ScopeRef| s.is_everywhere() || chain.contains(s);
1062                    let by_membership = self
1063                        .inner
1064                        .memberships
1065                        .held(&principal)
1066                        .iter()
1067                        .any(|m| in_chain(&m.scope) && self.lists(&m.role, grant));
1068                    let by_ceiling = layers
1069                        .iter()
1070                        .all(|layer| layer.0.iter().any(|(rg, s)| in_chain(s) && self.entry_allows(rg, grant)));
1071                    let scope = chain.first().cloned().unwrap_or_else(|| ScopeRef::named(t));
1072                    (by_membership && by_ceiling, scope)
1073                }
1074            },
1075        };
1076        if allowed {
1077            Ok(Reach {
1078                held_on: held_on.into(),
1079                live: Some(Live { gate: self.clone(), caller: caller.cloned(), grant: grant.clone(), everywhere: false }),
1080            })
1081        } else {
1082            Err(Refusal::MissingGrant { grant: grant.clone(), scope, roles: self.roles_listing(grant), held_on })
1083        }
1084    }
1085
1086    /// KEEL-31: the check for a method that acts on the whole service (it
1087    /// names no target because its target is everything: a key rotated, a
1088    /// process spawned, a peer connected). Allowed only where the grant is
1089    /// held on `*` — by a role held on `*` that lists it, and every ceiling
1090    /// layer allowing it on `*` — never because it is held on some scope. A
1091    /// scoped `admin`, or a session minted `admin@X`, is refused, naming `*`.
1092    /// The reach is `[*]` and stays live by this same rule.
1093    pub fn check_everywhere(&self, caller: Option<&AuthContext>, grant: &Grant) -> Result<Reach, Refusal> {
1094        let reach = match self.check(caller, grant, None) {
1095            Ok(reach) => reach,
1096            Err(Refusal::MissingGrant { grant, roles, held_on, .. }) => {
1097                return Err(Refusal::MissingGrant { grant, scope: ScopeRef::Everywhere, roles, held_on })
1098            }
1099            Err(other) => return Err(other),
1100        };
1101        if !reach.is_everywhere() {
1102            return Err(Refusal::MissingGrant {
1103                grant: grant.clone(),
1104                scope: ScopeRef::Everywhere,
1105                roles: self.roles_listing(grant),
1106                held_on: reach.held_on.into_owned(),
1107            });
1108        }
1109        // PERF.115-49: the check's own live part (this gate, this caller,
1110        // this grant), kept by the rule of `*` — not a second copy of each.
1111        let live = reach.live.map(|live| Live { everywhere: true, ..live });
1112        Ok(Reach { held_on: reach.held_on, live })
1113    }
1114
1115    /// The reach of a `public` method: what [`Gate::check`] would allow
1116    /// without a target, or an empty (still live) reach when the caller holds
1117    /// the grant nowhere or is anonymous. A public method is never refused.
1118    pub fn reach_of_public(&self, caller: Option<&AuthContext>, grant: &Grant) -> Reach {
1119        self.check(caller, grant, None).unwrap_or_else(|_| Reach {
1120            held_on: std::borrow::Cow::Borrowed(&[]),
1121            live: Some(Live { gate: self.clone(), caller: caller.cloned(), grant: grant.clone(), everywhere: false }),
1122        })
1123    }
1124}
1125
1126// ---------------------------------------------------------------------------
1127// Tests — the gate's decision table
1128// ---------------------------------------------------------------------------
1129
1130#[cfg(test)]
1131mod tests {
1132    use super::*;
1133    use std::sync::Mutex;
1134
1135    const ADA: &str = "key:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
1136    const BOB: &str = "key:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
1137
1138    /// Memberships as a mutable table, so a test can revoke one.
1139    #[derive(Default)]
1140    struct Members(Mutex<Vec<Membership>>);
1141    impl Members {
1142        fn grant(&self, who: &str, role: &str, scope: &str) {
1143            self.0.lock().unwrap().push(Membership {
1144                principal: who.parse().unwrap(),
1145                role: RoleName::new(role),
1146                scope: ScopeRef::parse(scope),
1147            });
1148        }
1149        fn revoke_all(&self) {
1150            self.0.lock().unwrap().clear();
1151        }
1152    }
1153    impl Memberships for Members {
1154        fn held(&self, who: &Principal) -> Vec<Membership> {
1155            self.0.lock().unwrap().iter().filter(|m| &m.principal == who).cloned().collect()
1156        }
1157    }
1158
1159    /// menger-shaped: a ticket `CODE-n` lives in itself, then `CODE`;
1160    /// MENGER and IDENTITY are disjoint, both hosted under PLEXUS.
1161    struct Shortcodes;
1162    impl Resolve for Shortcodes {
1163        fn chain(&self, target: &str) -> Option<Vec<ScopeRef>> {
1164            let code = target.split_once('-').map(|(c, _)| c).unwrap_or(target);
1165            let mut chain = Vec::new();
1166            if target.contains('-') {
1167                chain.push(ScopeRef::named(target));
1168            }
1169            match code {
1170                "MENGER" | "IDENTITY" => {
1171                    chain.push(ScopeRef::named(code));
1172                    chain.push(ScopeRef::named("PLEXUS"));
1173                }
1174                "PLEXUS" => chain.push(ScopeRef::named("PLEXUS")),
1175                _ => return None,
1176            }
1177            chain.push(ScopeRef::Everywhere);
1178            Some(chain)
1179        }
1180    }
1181
1182    fn roles() -> RoleTable {
1183        RoleTable::new()
1184            .define("viewer", ["tickets.get", "tickets.list"])
1185            .unwrap()
1186            .define("editor", ["viewer", "tickets.set_status"])
1187            .unwrap()
1188    }
1189
1190    fn gate(members: &Arc<Members>) -> Gate {
1191        Gate::new(members.clone(), Arc::new(roles()), Arc::new(Shortcodes))
1192    }
1193
1194    fn who(p: &str) -> AuthContext {
1195        AuthContext::for_principal(&p.parse().unwrap(), "s1", vec![], serde_json::Value::Null)
1196    }
1197
1198    fn with_ceiling(p: &str, ceiling: serde_json::Value) -> AuthContext {
1199        AuthContext::for_principal(&p.parse().unwrap(), "s1", vec![], serde_json::json!({ CEILING_KEY: ceiling }))
1200    }
1201
1202    fn g(s: &str) -> Grant {
1203        Grant::new(s)
1204    }
1205
1206    #[test]
1207    fn a_grant_no_role_lists_is_refused_to_all_but_admin() {
1208        let m = Arc::new(Members::default());
1209        m.grant(ADA, "editor", "*");
1210        m.grant(BOB, "admin", "MENGER");
1211        let gate = gate(&m);
1212        let err = gate.check(Some(&who(ADA)), &g("members.grant"), Some("MENGER-1")).unwrap_err();
1213        assert_eq!(
1214            err,
1215            Refusal::MissingGrant {
1216                grant: g("members.grant"),
1217                scope: ScopeRef::named("MENGER-1"),
1218                roles: vec![RoleName::new("admin")],
1219                held_on: vec![],
1220            }
1221        );
1222        assert!(gate.check(Some(&who(BOB)), &g("members.grant"), Some("MENGER-1")).is_ok());
1223        // admin on MENGER is not admin on IDENTITY.
1224        assert!(gate.check(Some(&who(BOB)), &g("members.grant"), Some("IDENTITY-1")).is_err());
1225    }
1226
1227    #[test]
1228    fn held_on_a_scope_allows_targets_in_its_chain_only() {
1229        let m = Arc::new(Members::default());
1230        m.grant(ADA, "editor", "MENGER");
1231        let gate = gate(&m);
1232        let reach = gate.check(Some(&who(ADA)), &g("tickets.set_status"), Some("MENGER-12")).unwrap();
1233        assert_eq!(reach.held_on(), &[ScopeRef::named("MENGER")]);
1234        let err = gate.check(Some(&who(ADA)), &g("tickets.set_status"), Some("IDENTITY-1")).unwrap_err();
1235        assert_eq!(
1236            err,
1237            Refusal::MissingGrant {
1238                grant: g("tickets.set_status"),
1239                scope: ScopeRef::named("IDENTITY-1"),
1240                roles: vec![RoleName::new("editor"), RoleName::new("admin")],
1241                held_on: vec![ScopeRef::named("MENGER")],
1242            }
1243        );
1244        assert_eq!(err.to_string(), "needs tickets.set_status on IDENTITY-1");
1245        // A target nothing resolves is refused.
1246        assert!(gate.check(Some(&who(ADA)), &g("tickets.get"), Some("NOPE-1")).is_err());
1247    }
1248
1249    #[test]
1250    fn held_on_everywhere_allows_any_target_and_reach_is_everywhere() {
1251        let m = Arc::new(Members::default());
1252        m.grant(ADA, "viewer", "*");
1253        m.grant(ADA, "viewer", "MENGER");
1254        let gate = gate(&m);
1255        let reach = gate.check(Some(&who(ADA)), &g("tickets.get"), Some("IDENTITY-3")).unwrap();
1256        assert!(reach.is_everywhere());
1257        assert_eq!(reach.held_on(), &[ScopeRef::Everywhere]);
1258        assert!(gate.check(Some(&who(ADA)), &g("tickets.list"), None).unwrap().is_everywhere());
1259        // viewer does not list set_status, wherever it is held.
1260        assert!(gate.check(Some(&who(ADA)), &g("tickets.set_status"), Some("IDENTITY-3")).is_err());
1261    }
1262
1263    #[test]
1264    fn without_a_target_held_anywhere_suffices_and_reach_says_where() {
1265        let m = Arc::new(Members::default());
1266        m.grant(ADA, "viewer", "MENGER");
1267        m.grant(ADA, "viewer", "IDENTITY");
1268        let gate = gate(&m);
1269        let reach = gate.check(Some(&who(ADA)), &g("tickets.list"), None).unwrap();
1270        assert_eq!(reach.held_on(), &[ScopeRef::named("IDENTITY"), ScopeRef::named("MENGER")]);
1271        assert!(reach.allows("MENGER-4"));
1272        assert!(!reach.allows("PLEXUS-1"));
1273        let err = gate.check(Some(&who(BOB)), &g("tickets.list"), None).unwrap_err();
1274        assert!(matches!(err, Refusal::MissingGrant { ref scope, .. } if scope.is_everywhere()));
1275    }
1276
1277    #[test]
1278    fn a_ceiling_narrows_the_membership() {
1279        let m = Arc::new(Members::default());
1280        m.grant(ADA, "editor", "MENGER");
1281        let gate = gate(&m);
1282        let narrowed = with_ceiling(ADA, serde_json::json!(["editor@MENGER-12"]));
1283        assert!(gate.check(Some(&narrowed), &g("tickets.set_status"), Some("MENGER-12")).is_ok());
1284        assert!(gate.check(Some(&narrowed), &g("tickets.set_status"), Some("MENGER-13")).is_err());
1285        // The reach of a target-less read is the meet: MENGER-12, inside MENGER.
1286        let reach = gate.check(Some(&narrowed), &g("tickets.list"), None).unwrap();
1287        assert_eq!(reach.held_on(), &[ScopeRef::named("MENGER-12")]);
1288        // A grant-entry ceiling: only tickets.get, anywhere the membership allows.
1289        let only_get = with_ceiling(ADA, serde_json::json!([["tickets.get@*"]]));
1290        assert!(gate.check(Some(&only_get), &g("tickets.get"), Some("MENGER-1")).is_ok());
1291        let err = gate.check(Some(&only_get), &g("tickets.set_status"), Some("MENGER-1")).unwrap_err();
1292        assert!(matches!(err, Refusal::MissingGrant { ref held_on, .. } if held_on.is_empty()));
1293        // Two layers: both must allow.
1294        let layered = with_ceiling(ADA, serde_json::json!([["editor@*"], ["viewer@MENGER"]]));
1295        assert!(gate.check(Some(&layered), &g("tickets.get"), Some("MENGER-1")).is_ok());
1296        assert!(gate.check(Some(&layered), &g("tickets.set_status"), Some("MENGER-1")).is_err());
1297        // A ceiling never widens: editor@IDENTITY grants nothing there.
1298        let wider = with_ceiling(ADA, serde_json::json!(["editor@IDENTITY"]));
1299        assert!(gate.check(Some(&wider), &g("tickets.get"), Some("IDENTITY-1")).is_err());
1300        // An unreadable ceiling allows nothing.
1301        let bad = with_ceiling(ADA, serde_json::json!("editor@*"));
1302        assert!(gate.check(Some(&bad), &g("tickets.get"), Some("MENGER-1")).is_err());
1303    }
1304
1305    #[test]
1306    fn role_inclusion_flattens_and_must_name_an_earlier_role() {
1307        let r = roles();
1308        let editor = r.grants(&RoleName::new("editor")).unwrap();
1309        assert!(editor.contains(&g("tickets.get")) && editor.contains(&g("tickets.set_status")));
1310        let viewer = r.grants(&RoleName::new("viewer")).unwrap();
1311        assert!(!viewer.contains(&g("tickets.set_status")));
1312        assert_eq!(
1313            RoleTable::new().define("editor", ["viewer"]).unwrap_err(),
1314            RoleTableError::UnknownRole { role: "editor".into(), includes: "viewer".into() }
1315        );
1316        // admin is built in: holds every grant, whatever the table says.
1317        assert_eq!(r.grants(&RoleName::new("admin")), Some(GrantSet::All));
1318        // from_lists merges one role's lists from several activations.
1319        let merged = RoleTable::from_lists([("editor", vec!["tickets.get"]), ("editor", vec!["comments.add"])]);
1320        let e = merged.grants(&RoleName::new("editor")).unwrap();
1321        assert!(e.contains(&g("tickets.get")) && e.contains(&g("comments.add")));
1322    }
1323
1324    #[test]
1325    fn anonymous_is_unauthenticated() {
1326        let m = Arc::new(Members::default());
1327        let gate = gate(&m);
1328        assert_eq!(gate.check(None, &g("tickets.get"), Some("MENGER-1")).unwrap_err(), Refusal::Unauthenticated);
1329        assert_eq!(
1330            gate.check(Some(&AuthContext::anonymous()), &g("tickets.list"), None).unwrap_err(),
1331            Refusal::Unauthenticated
1332        );
1333        // A public method's reach for an anonymous caller: empty, never refused.
1334        assert!(gate.reach_of_public(None, &g("auth.login")).is_empty());
1335    }
1336
1337    #[test]
1338    fn a_live_reach_follows_grants_as_they_stand() {
1339        let m = Arc::new(Members::default());
1340        m.grant(ADA, "viewer", "MENGER");
1341        let gate = gate(&m);
1342        let reach = gate.check(Some(&who(ADA)), &g("tickets.list"), None).unwrap();
1343        assert!(reach.allows("MENGER-1"));
1344        assert!(reach.current().is_some());
1345        m.revoke_all();
1346        assert!(!reach.allows("MENGER-1"));
1347        assert!(reach.current().is_none());
1348        // Without a gate, everything.
1349        assert!(Reach::everywhere().allows("ANY-1") && Reach::everywhere().current().is_some());
1350    }
1351
1352    #[test]
1353    fn scope_refs_and_ceilings_round_trip() {
1354        assert_eq!(serde_json::to_string(&ScopeRef::Everywhere).unwrap(), "\"*\"");
1355        assert_eq!(serde_json::from_str::<ScopeRef>("\"MENGER\"").unwrap(), ScopeRef::named("MENGER"));
1356        let c = Ceiling::parse(["editor@MENGER-12", "tickets.get@*"]).unwrap();
1357        assert_eq!(c.0[0], (RoleOrGrant::Role(RoleName::new("editor")), ScopeRef::named("MENGER-12")));
1358        assert_eq!(c.0[1], (RoleOrGrant::Grant(g("tickets.get")), ScopeRef::Everywhere));
1359        assert_eq!(c.text(), vec!["editor@MENGER-12", "tickets.get@*"]);
1360        assert!(Ceiling::parse(["editor"]).is_err());
1361    }
1362
1363    /// A session table with one switch: signed out or not.
1364    #[derive(Default)]
1365    struct Switch(std::sync::atomic::AtomicBool);
1366    impl Liveness for Switch {
1367        fn alive(&self, _: &AuthContext) -> Result<(), String> {
1368            if self.0.load(std::sync::atomic::Ordering::SeqCst) {
1369                Err("you have signed out: sign in again".into())
1370            } else {
1371                Ok(())
1372            }
1373        }
1374    }
1375
1376    /// AUTH-11: a signed-out session holds nothing — not even admin on `*`
1377    /// — and a live reach taken before the sign-out ends with it.
1378    #[test]
1379    fn a_session_that_ended_holds_nothing() {
1380        let m = Arc::new(Members::default());
1381        m.grant(ADA, "admin", "*");
1382        let out = Arc::new(Switch::default());
1383        let gate = gate(&m).with_liveness(out.clone());
1384        let reach = gate.check(Some(&who(ADA)), &g("auth.grant"), None).expect("admin before sign-out");
1385        assert!(reach.allows("MENGER-1"));
1386        out.0.store(true, std::sync::atomic::Ordering::SeqCst);
1387        let ended = Refusal::Ended { reason: "you have signed out: sign in again".into() };
1388        assert_eq!(gate.check(Some(&who(ADA)), &g("auth.grant"), None).unwrap_err(), ended);
1389        assert_eq!(gate.check(Some(&who(ADA)), &g("tickets.get"), Some("MENGER-1")).unwrap_err(), ended);
1390        assert!(!reach.allows("MENGER-1"), "a stream's next event sees it");
1391        assert!(reach.current().is_none());
1392        assert!(gate.reach_of_public(Some(&who(ADA)), &g("auth.grant")).is_empty());
1393        // Anonymous is not "ended": still plain Unauthenticated.
1394        assert_eq!(gate.check(None, &g("auth.grant"), None).unwrap_err(), Refusal::Unauthenticated);
1395    }
1396
1397    /// AUTH-11: past its `expires_at` stamp, a sign-in is over even with
1398    /// no liveness hook.
1399    #[test]
1400    fn an_expired_sign_in_holds_nothing() {
1401        let m = Arc::new(Members::default());
1402        m.grant(ADA, "admin", "*");
1403        let gate = gate(&m);
1404        let past = AuthContext::for_principal(&ADA.parse().unwrap(), "s1", vec![], serde_json::json!({ "expires_at": 1 }));
1405        assert!(matches!(gate.check(Some(&past), &g("auth.grant"), None), Err(Refusal::Ended { .. })));
1406        let future = AuthContext::for_principal(&ADA.parse().unwrap(), "s1", vec![], serde_json::json!({ "expires_at": i64::MAX }));
1407        assert!(gate.check(Some(&future), &g("auth.grant"), None).is_ok());
1408    }
1409
1410    /// PERF-15: a fingerprint is what the gate's answers read of a caller —
1411    /// equal for two principals holding the same, different when a
1412    /// membership or the ceiling differs, `None` when anonymous — and
1413    /// `held_on_by` answers from it exactly what `held_on` answers.
1414    #[test]
1415    fn a_fingerprint_is_what_the_answers_read() {
1416        let m = Arc::new(Members::default());
1417        m.grant(ADA, "viewer", "IDENTITY");
1418        m.grant(ADA, "editor", "MENGER");
1419        m.grant(BOB, "editor", "MENGER");
1420        m.grant(BOB, "viewer", "IDENTITY");
1421        m.grant(BOB, "editor", "MENGER");
1422        let gate = gate(&m);
1423        let (ada, bob) = (gate.fingerprint(&who(ADA)).unwrap(), gate.fingerprint(&who(BOB)).unwrap());
1424        assert_eq!(ada, bob, "the same holdings, in another order and once more: one fingerprint");
1425        assert_eq!(gate.fingerprint(&AuthContext::anonymous()), None);
1426        let narrow = with_ceiling(ADA, serde_json::json!(["editor@MENGER-12"]));
1427        let narrowed = gate.fingerprint(&narrow).unwrap();
1428        assert_ne!(narrowed, ada, "a ceiling: another fingerprint");
1429        let unreadable = gate.fingerprint(&with_ceiling(ADA, serde_json::json!("editor@*"))).unwrap();
1430        assert_ne!(unreadable, ada, "an unreadable ceiling allows nothing: not the unbounded caller's");
1431        for (ctx, fp) in [(&who(ADA), &ada), (&narrow, &narrowed), (&with_ceiling(ADA, serde_json::json!("editor@*")), &unreadable)] {
1432            for grant in ["tickets.get", "tickets.set_status", "tickets.delete", "members.grant"] {
1433                assert_eq!(gate.held_on_by(fp, &g(grant)), gate.held_on(ctx, &g(grant)), "{grant}");
1434            }
1435        }
1436        assert_eq!(gate.held_on_by(&narrowed, &g("tickets.get")), vec![ScopeRef::named("MENGER-12")]);
1437        m.revoke_all();
1438        assert_ne!(gate.fingerprint(&who(ADA)).unwrap(), ada, "a revoke: another fingerprint");
1439    }
1440
1441    /// KEEL-31 (the review's probe, KEEL-28): `admin` held on one ticket is
1442    /// admitted to a method with no target by [`Gate::check`] — held
1443    /// somewhere — and refused by [`Gate::check_everywhere`], naming `*`; so
1444    /// is a session minted narrower than `*`. Held on `*`, it is allowed,
1445    /// and its reach stays live by the same rule.
1446    #[test]
1447    fn a_whole_service_method_needs_its_grant_on_everywhere() {
1448        let m = Arc::new(Members::default());
1449        m.grant(ADA, "admin", "MENGER-5");
1450        m.grant(BOB, "admin", "*");
1451        let gate = gate(&m);
1452        let grow = g("dyn.grow");
1453        assert_eq!(gate.check(Some(&who(ADA)), &grow, None).unwrap().held_on(), [ScopeRef::named("MENGER-5")]);
1454        match gate.check_everywhere(Some(&who(ADA)), &grow) {
1455            Err(Refusal::MissingGrant { scope, held_on, .. }) => {
1456                assert_eq!(scope, ScopeRef::Everywhere);
1457                assert_eq!(held_on, [ScopeRef::named("MENGER-5")]);
1458            }
1459            other => panic!("a scoped admin: {other:?}"),
1460        }
1461        let reach = gate.check_everywhere(Some(&who(BOB)), &grow).unwrap();
1462        assert!(reach.is_everywhere());
1463        for ceiling in [serde_json::json!(["admin@MENGER-5"]), serde_json::json!(["viewer@*"]), serde_json::json!("admin@*")] {
1464            let capped = with_ceiling(BOB, ceiling.clone());
1465            assert!(gate.check_everywhere(Some(&capped), &grow).is_err(), "ceiling {ceiling}");
1466        }
1467        assert!(gate.check_everywhere(Some(&with_ceiling(BOB, serde_json::json!(["dyn.grow@*"]))), &grow).is_ok());
1468        assert!(gate.check_everywhere(Some(&with_ceiling(ADA, serde_json::json!(["admin@*"]))), &grow).is_err(), "a ceiling never widens");
1469        assert_eq!(gate.check_everywhere(None, &grow).err(), Some(Refusal::Unauthenticated));
1470        // Live: narrowed to a scope while it runs, the reach is gone.
1471        m.revoke_all();
1472        m.grant(BOB, "admin", "MENGER");
1473        assert!(reach.current().is_none());
1474        assert!(reach.recheck().is_err());
1475        assert!(!reach.allows("MENGER-1"));
1476    }
1477}