1use std::collections::{BTreeMap, BTreeSet};
40use std::fmt;
41use std::sync::{Arc, RwLock};
42
43use async_stream::stream;
44use async_trait::async_trait;
45use futures::Stream;
46use schemars::JsonSchema;
47use serde::{Deserialize, Serialize};
48
49use plexus_auth_core::grants::{
50 Ceiling, Gate, Grant, GrantSet, GrantsGeneration, GrantsMove, Liveness, Membership, Memberships, Reach, Resolve, Roles, ScopeRef, ADMIN,
51};
52use plexus_auth_core::identity::Principal;
53use plexus_auth_core::RoleName;
54
55use super::auth::AuthContext;
56use super::auth_params as param;
57use super::schema::{MethodRole, PluginSchema};
58
59pub const SIGNED_IN_GRANTS: [&str; 3] = ["auth.whoami", "auth.logout", "auth.requires"];
63
64#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
70#[serde(rename_all = "snake_case")]
71pub enum ProviderKind {
72 Browser,
75 Password,
77 Key,
79}
80
81#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
83pub struct Provider {
84 pub name: String,
86 pub kind: ProviderKind,
87 #[serde(default, skip_serializing_if = "Option::is_none")]
89 pub label: Option<String>,
90}
91
92#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
97#[serde(rename_all = "snake_case")]
98pub enum LoginFlow {
99 Browser { redirect: String },
104 Code { code: String, state: String },
107 Password { username: String, password: String },
109 Session {
113 #[serde(default)]
114 ttl_secs: Option<u64>,
115 #[serde(default)]
116 ceiling: Option<Vec<String>>,
117 },
118}
119
120#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
122pub struct Session {
123 pub token: String,
125 pub principal: String,
127 #[serde(default, skip_serializing_if = "Option::is_none")]
129 pub agent: Option<String>,
130 #[serde(default, skip_serializing_if = "Option::is_none")]
132 pub name: Option<String>,
133 pub expires_at: i64,
135 #[serde(default)]
137 pub ceiling: Vec<String>,
138}
139
140#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
142pub struct Waiting {
143 pub principal: String,
144 #[serde(default, skip_serializing_if = "Option::is_none")]
145 pub name: Option<String>,
146 #[serde(default, skip_serializing_if = "Option::is_none")]
148 pub provider: Option<String>,
149 pub since: i64,
151}
152
153#[derive(Debug, Clone, PartialEq, Eq)]
155pub enum LoginAnswer {
156 LoginUrl { url: String, state: String },
158 Session(Session),
159}
160
161#[derive(Debug, Clone, PartialEq, Eq)]
163pub enum SignupAnswer {
164 Waiting(Waiting),
165 LoginUrl { url: String, state: String },
166 Session(Session),
167}
168
169#[derive(Debug, Clone, PartialEq, Eq)]
171pub struct AuthFailure(pub String);
172
173impl AuthFailure {
174 pub fn new(message: impl Into<String>) -> Self {
175 Self(message.into())
176 }
177}
178
179impl fmt::Display for AuthFailure {
180 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
181 f.write_str(&self.0)
182 }
183}
184
185impl std::error::Error for AuthFailure {}
186
187#[derive(Debug, Clone, PartialEq, Eq)]
189pub struct StoreError(pub String);
190
191impl StoreError {
192 pub fn new(message: impl Into<String>) -> Self {
193 Self(message.into())
194 }
195}
196
197impl fmt::Display for StoreError {
198 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
199 f.write_str(&self.0)
200 }
201}
202
203impl std::error::Error for StoreError {}
204
205#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
207pub struct MembershipEntry {
208 pub role: String,
209 pub scope: String,
210}
211
212#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
214#[serde(tag = "type", rename_all = "snake_case")]
215pub enum AuthEvent {
216 Provider {
218 name: String,
219 kind: ProviderKind,
220 #[serde(default, skip_serializing_if = "Option::is_none")]
221 label: Option<String>,
222 },
223 LoginUrl { url: String, state: String },
225 Session {
227 token: String,
228 principal: String,
229 #[serde(default, skip_serializing_if = "Option::is_none")]
230 agent: Option<String>,
231 #[serde(default, skip_serializing_if = "Option::is_none")]
232 name: Option<String>,
233 expires_at: i64,
234 #[serde(default)]
235 ceiling: Vec<String>,
236 },
237 Waiting {
239 principal: String,
240 #[serde(default, skip_serializing_if = "Option::is_none")]
241 name: Option<String>,
242 #[serde(default, skip_serializing_if = "Option::is_none")]
243 provider: Option<String>,
244 since: i64,
245 },
246 Whoami {
248 principal: String,
249 #[serde(default, skip_serializing_if = "Option::is_none")]
250 name: Option<String>,
251 #[serde(default, skip_serializing_if = "Option::is_none")]
252 agent: Option<String>,
253 memberships: Vec<MembershipEntry>,
254 ceiling: Vec<String>,
255 },
256 LoggedOut { principal: String },
258 Requires {
260 method: String,
261 grant: String,
262 #[serde(default, skip_serializing_if = "Option::is_none")]
263 target: Option<String>,
264 roles: Vec<String>,
265 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
266 public: bool,
267 },
268 Role {
271 role: String,
272 grants: Vec<String>,
273 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
274 all: bool,
275 },
276 Granted { principal: String, role: String, scope: String },
278 Revoked { principal: String, scope: String, roles: Vec<String> },
280 Error {
283 message: String,
284 #[serde(default, skip_serializing_if = "Option::is_none")]
285 error_kind: Option<String>,
286 #[serde(default, skip_serializing_if = "Option::is_none")]
287 grant: Option<String>,
288 #[serde(default, skip_serializing_if = "Option::is_none")]
289 scope: Option<String>,
290 #[serde(default, skip_serializing_if = "Option::is_none")]
291 roles: Option<Vec<String>>,
292 #[serde(default, skip_serializing_if = "Option::is_none")]
293 held_on: Option<Vec<String>>,
294 },
295}
296
297impl AuthEvent {
298 fn error(message: impl Into<String>) -> Self {
299 Self::Error { message: message.into(), error_kind: None, grant: None, scope: None, roles: None, held_on: None }
300 }
301}
302
303impl From<Session> for AuthEvent {
304 fn from(s: Session) -> Self {
305 Self::Session {
306 token: s.token,
307 principal: s.principal,
308 agent: s.agent,
309 name: s.name,
310 expires_at: s.expires_at,
311 ceiling: s.ceiling,
312 }
313 }
314}
315
316impl From<Waiting> for AuthEvent {
317 fn from(w: Waiting) -> Self {
318 Self::Waiting { principal: w.principal, name: w.name, provider: w.provider, since: w.since }
319 }
320}
321
322#[async_trait]
330pub trait AuthBackend: Send + Sync + 'static {
331 fn providers(&self) -> Vec<Provider>;
333
334 async fn login(&self, caller: Option<&AuthContext>, flow: LoginFlow) -> Result<LoginAnswer, AuthFailure>;
341
342 async fn signup(&self, caller: Option<&AuthContext>, via: Option<String>) -> Result<SignupAnswer, AuthFailure>;
347
348 async fn ask_access(&self, caller: &AuthContext, via: Option<String>) -> Result<Waiting, AuthFailure>;
351
352 fn waiting(&self) -> Vec<Waiting>;
355
356 async fn logout(&self, caller: &AuthContext) -> Result<(), AuthFailure>;
359
360 fn alive(&self, caller: &AuthContext) -> Result<(), String>;
367}
368
369struct BackendLiveness(Arc<dyn AuthBackend>);
371
372impl Liveness for BackendLiveness {
373 fn alive(&self, caller: &AuthContext) -> Result<(), String> {
374 self.0.alive(caller)
375 }
376}
377
378#[async_trait]
381pub trait RoleStore: Roles + 'static {
382 async fn set(&self, role: &RoleName, grants: GrantSet) -> Result<(), StoreError>;
384}
385
386#[async_trait]
388pub trait MembershipStore: Memberships + 'static {
389 async fn grant(&self, membership: Membership) -> Result<(), StoreError>;
391
392 async fn revoke(
395 &self,
396 principal: &Principal,
397 role: Option<&RoleName>,
398 scope: &ScopeRef,
399 ) -> Result<Vec<RoleName>, StoreError>;
400}
401
402#[derive(Clone)]
404pub struct AuthSetup {
405 pub backend: Arc<dyn AuthBackend>,
406 pub roles: Arc<dyn RoleStore>,
407 pub memberships: Arc<dyn MembershipStore>,
408 pub resolve: Arc<dyn Resolve>,
409 pub generation: Option<GrantsGeneration>,
414}
415
416impl AuthSetup {
417 pub fn new(
418 backend: Arc<dyn AuthBackend>,
419 roles: Arc<dyn RoleStore>,
420 memberships: Arc<dyn MembershipStore>,
421 resolve: Arc<dyn Resolve>,
422 ) -> Self {
423 Self { backend, roles, memberships, resolve, generation: None }
424 }
425
426 pub fn with_generation(mut self, generation: GrantsGeneration) -> Self {
429 self.generation = Some(generation);
430 self
431 }
432}
433
434#[derive(Debug, Clone, PartialEq, Eq)]
440pub struct Requirement {
441 pub grant: String,
442 pub target: Option<String>,
443 pub public: bool,
444}
445
446#[derive(Clone, Default)]
450pub struct Catalog(Arc<RwLock<BTreeMap<String, Requirement>>>, Arc<RwLock<super::slots::Slots>>);
451
452impl Catalog {
453 pub(crate) fn add(&self, schema: &PluginSchema) {
456 self.1.write().unwrap_or_else(|p| p.into_inner()).add(schema);
457 let mut map = self.0.write().unwrap_or_else(|p| p.into_inner());
458 for m in &schema.methods {
459 if m.is_auto_schema() || !matches!(m.role, MethodRole::Rpc) {
460 continue;
461 }
462 let grant = m.grant_or(&schema.namespace);
463 map.insert(grant.clone(), Requirement { grant, target: m.target.clone(), public: m.public });
464 }
465 }
466
467 pub(crate) fn remove_under(&self, ns: &str) {
470 let prefix = format!("{ns}.");
471 self.0.write().unwrap_or_else(|p| p.into_inner()).retain(|k, _| !k.starts_with(&prefix));
472 }
473
474 pub(crate) fn add_slots(&self, untyped: &[String]) {
476 let mut slots = self.1.write().unwrap_or_else(|p| p.into_inner());
477 let mut map = self.0.write().unwrap_or_else(|p| p.into_inner());
478 for path in untyped {
479 slots.add_untyped(path);
480 map.insert(path.clone(), Requirement { grant: path.clone(), target: None, public: false });
481 }
482 }
483
484 pub fn get(&self, method: &str) -> Option<Requirement> {
487 let map = self.0.read().unwrap_or_else(|p| p.into_inner());
488 if let Some(r) = map.get(method) {
489 return Some(r.clone());
490 }
491 let key = self.1.read().unwrap_or_else(|p| p.into_inner()).resolve(method)?;
492 map.get(&key).cloned()
493 }
494
495 pub fn knows(&self, grant: &str) -> bool {
497 self.0.read().unwrap_or_else(|p| p.into_inner()).contains_key(grant)
498 }
499}
500
501#[derive(Clone)]
509pub struct AuthActivation {
510 inner: Arc<AuthInner>,
511}
512
513struct AuthInner {
514 backend: Arc<dyn AuthBackend>,
515 roles: Arc<dyn RoleStore>,
516 memberships: Arc<dyn MembershipStore>,
517 gate: Gate,
518 catalog: Catalog,
519}
520
521struct WithEverywhere(Arc<dyn Resolve>);
524
525impl Resolve for WithEverywhere {
526 fn chain(&self, target: &str) -> Option<Vec<ScopeRef>> {
527 if matches!(target.trim(), "*" | "self") || target.trim().starts_with('/') {
532 return Some(vec![ScopeRef::Everywhere]);
533 }
534 self.0.chain(target)
535 }
536}
537
538fn checked_ceiling(entries: &[String]) -> Result<Vec<String>, String> {
542 entries
543 .iter()
544 .map(|e| {
545 let (left, scope) = e.trim().split_once('@').ok_or_else(|| format!("`{e}` is not role@SCOPE or grant@SCOPE"))?;
546 let scope = ScopeRef::parse_checked(scope.trim()).map_err(|e| e.to_string())?;
547 Ok(format!("{}@{scope}", left.trim()))
548 })
549 .collect()
550}
551
552impl AuthActivation {
553 pub(crate) fn mount(setup: AuthSetup, catalog: Catalog) -> (Self, Gate) {
555 let memberships: Arc<dyn Memberships> = setup.memberships.clone();
556 let roles: Arc<dyn Roles> = setup.roles.clone();
557 let mut gate = Gate::new(memberships, roles, Arc::new(WithEverywhere(setup.resolve)))
558 .with_liveness(Arc::new(BackendLiveness(setup.backend.clone())));
559 if let Some(generation) = setup.generation {
560 gate = gate.with_generation(generation);
561 }
562 let auth = Self {
563 inner: Arc::new(AuthInner {
564 backend: setup.backend,
565 roles: setup.roles,
566 memberships: setup.memberships,
567 gate: gate.clone(),
568 catalog,
569 }),
570 };
571 (auth, gate)
572 }
573}
574
575fn principal_of(ctx: &AuthContext) -> Option<Principal> {
576 ctx.principal()
577}
578
579pub const EVERYWHERE: &[&str] = &["role_set", "waiting"];
582
583fn meta(ctx: &AuthContext, key: &str) -> Option<String> {
584 ctx.get_metadata_string(key).filter(|s| !s.is_empty())
585}
586
587fn needs_everywhere(gate: &Gate, grant: &str, reach: &Reach) -> AuthEvent {
589 let g = Grant::new(grant);
590 AuthEvent::Error {
591 message: format!("needs {grant} on *"),
592 error_kind: Some("forbidden".into()),
593 grant: Some(grant.into()),
594 scope: Some("*".into()),
595 roles: Some(gate.roles_listing(&g).iter().map(|r| r.as_str().to_string()).collect()),
596 held_on: Some(reach.held_on().iter().map(|s| s.as_str().to_string()).collect()),
597 }
598}
599
600fn holds_where_written(gate: &Gate, auth: &AuthContext, reach: &Reach, grant: &str, scopes: &[&str]) -> Result<(), Box<AuthEvent>> {
607 let g = Grant::new(grant);
608 if reach.grant() != Some(&g) {
609 return Err(Box::new(needs_on(gate, grant, "*", reach.held_on().iter().map(|s| s.as_str().to_string()).collect())));
610 }
611 for scope in scopes {
612 match gate.check(Some(auth), &g, Some(scope)) {
613 Ok(_) => {}
614 Err(plexus_auth_core::grants::Refusal::MissingGrant { scope, held_on, .. }) => {
615 return Err(Box::new(needs_on(gate, grant, scope.as_str(), held_on.iter().map(|s| s.as_str().to_string()).collect())));
616 }
617 Err(plexus_auth_core::grants::Refusal::Ended { reason }) => return Err(Box::new(AuthEvent::error(reason))),
618 Err(plexus_auth_core::grants::Refusal::Unauthenticated) => return Err(Box::new(AuthEvent::error("sign in first"))),
619 }
620 }
621 Ok(())
622}
623
624fn needs_on(gate: &Gate, grant: &str, scope: &str, held_on: Vec<String>) -> AuthEvent {
626 AuthEvent::Error {
627 message: format!("needs {grant} on {scope}"),
628 error_kind: Some("forbidden".into()),
629 grant: Some(grant.into()),
630 scope: Some(scope.into()),
631 roles: Some(gate.roles_listing(&Grant::new(grant)).iter().map(|r| r.as_str().to_string()).collect()),
632 held_on: Some(held_on),
633 }
634}
635
636fn role_event(role: &RoleName, grants: Option<GrantSet>) -> AuthEvent {
637 match grants {
638 Some(GrantSet::All) => AuthEvent::Role { role: role.as_str().into(), grants: Vec::new(), all: true },
639 Some(GrantSet::Listed(set)) => AuthEvent::Role {
640 role: role.as_str().into(),
641 grants: set.iter().map(|g| g.as_str().to_string()).collect(),
642 all: false,
643 },
644 None => AuthEvent::Role { role: role.as_str().into(), grants: Vec::new(), all: false },
645 }
646}
647
648#[plexus_macros::activation(
649 version = "1.0.0",
650 description = "Sign in, who am I, what does this need",
651 roles(member = ["whoami", "logout", "requires"]),
652 typed_params,
655)]
656impl AuthActivation {
657 #[plexus_macros::method(public, group = "sign in", description = "The ways in this server offers")]
659 async fn providers(&self) -> impl Stream<Item = AuthEvent> + Send + 'static {
660 let providers = self.inner.backend.providers();
661 stream! {
662 for p in providers {
663 yield AuthEvent::Provider { name: p.name, kind: p.kind, label: p.label };
664 }
665 }
666 }
667
668 #[plexus_macros::method(
672 public,
673 group = "sign in",
674 description = "Sign in — a person through the browser, an agent with its key",
675 params(flow = "browser {redirect} | code {code, state} | password {username, password} | session {ttl_secs?, ceiling?}")
676 )]
677 async fn login(&self, auth: Option<&AuthContext>, flow: LoginFlow) -> impl Stream<Item = AuthEvent> + Send + 'static {
678 let inner = self.inner.clone();
679 let caller = auth.cloned();
680 let mut flow = flow;
681 stream! {
682 if let LoginFlow::Session { ceiling: Some(entries), .. } = &mut flow {
683 if let Err(e) = Ceiling::parse(entries.iter()) {
684 yield AuthEvent::error(format!("ceiling: {e}"));
685 return;
686 }
687 match checked_ceiling(entries) {
690 Ok(checked) => *entries = checked,
691 Err(e) => {
692 yield AuthEvent::error(format!("ceiling: {e}"));
693 return;
694 }
695 }
696 }
697 if matches!(flow, LoginFlow::Session { .. }) && caller.as_ref().and_then(principal_of).is_none() {
698 yield AuthEvent::error("a session needs a connection that is someone: a key proof at the upgrade, or a session");
699 return;
700 }
701 match inner.backend.login(caller.as_ref(), flow).await {
702 Ok(LoginAnswer::LoginUrl { url, state }) => yield AuthEvent::LoginUrl { url, state },
703 Ok(LoginAnswer::Session(s)) => yield s.into(),
704 Err(e) => yield AuthEvent::error(e.0),
705 }
706 }
707 }
708
709 #[plexus_macros::method(
713 public,
714 group = "sign in",
715 description = "Create an account, or ask for access",
716 params(via = "The provider to sign up through, where the server offers several")
717 )]
718 async fn signup(&self, auth: Option<&AuthContext>, via: Option<param::ProviderName>) -> impl Stream<Item = AuthEvent> + Send + 'static {
719 let inner = self.inner.clone();
720 let caller = auth.cloned();
721 let via = via.map(param::ProviderName::into_string);
722 stream! {
723 let holds_none = caller
724 .as_ref()
725 .and_then(principal_of)
726 .map(|p| inner.memberships.own_held(&p).is_empty());
727 let answer = match (holds_none, caller.as_ref()) {
728 (Some(true), Some(ctx)) => inner.backend.ask_access(ctx, via).await.map(SignupAnswer::Waiting),
729 _ => inner.backend.signup(caller.as_ref(), via).await,
730 };
731 match answer {
732 Ok(SignupAnswer::Waiting(w)) => yield w.into(),
733 Ok(SignupAnswer::LoginUrl { url, state }) => yield AuthEvent::LoginUrl { url, state },
734 Ok(SignupAnswer::Session(s)) => yield s.into(),
735 Err(e) => yield AuthEvent::error(e.0),
736 }
737 }
738 }
739
740 #[plexus_macros::method(group = "you", description = "Who you are: principal, roles held where, ceiling")]
743 async fn whoami(&self, auth: &AuthContext) -> impl Stream<Item = AuthEvent> + Send + 'static {
744 let inner = self.inner.clone();
745 let ctx = auth.clone();
746 stream! {
747 let Some(p) = principal_of(&ctx) else {
748 yield AuthEvent::error("sign in first");
749 return;
750 };
751 let memberships = inner
752 .memberships
753 .held(&p)
754 .into_iter()
755 .map(|m| MembershipEntry { role: m.role.as_str().into(), scope: m.scope.as_str().into() })
756 .collect();
757 let ceiling = Ceiling::layers_of(&ctx)
758 .map(|layers| layers.iter().flat_map(|l| l.text()).collect())
759 .unwrap_or_default();
760 yield AuthEvent::Whoami {
761 principal: p.to_string(),
762 name: meta(&ctx, "name"),
763 agent: meta(&ctx, "agent"),
764 memberships,
765 ceiling,
766 };
767 }
768 }
769
770 #[plexus_macros::method(group = "you", description = "Sign out: end this session")]
772 async fn logout(&self, auth: &AuthContext) -> impl Stream<Item = AuthEvent> + Send + 'static {
773 let inner = self.inner.clone();
774 let ctx = auth.clone();
775 stream! {
776 let principal = principal_of(&ctx).map(|p| p.to_string()).unwrap_or_default();
777 let moving = MovesOnDrop::armed(&inner.gate, GrantsMove::SignOut);
779 let out = inner.backend.logout(&ctx).await;
780 moving.done(out.is_ok());
781 match out {
782 Ok(()) => {
783 yield AuthEvent::LoggedOut { principal }
784 }
785 Err(e) => yield AuthEvent::error(e.0),
786 }
787 }
788 }
789
790 #[plexus_macros::method(
793 group = "you",
794 description = "What a method needs: its grant, target, and the roles that list it",
795 params(method = "The method, as <activation>.<method>: tickets.set_status"),
796 example(note = "what changing a ticket's status needs", params = r#"{"method": "tickets.set_status"}"#)
797 )]
798 async fn requires(&self, auth: &AuthContext, method: param::MethodPath) -> impl Stream<Item = AuthEvent> + Send + 'static {
799 let _ = auth;
800 let inner = self.inner.clone();
801 stream! {
802 match inner.catalog.get(method.as_str()) {
803 None => yield AuthEvent::error(format!("no method {method} here")),
804 Some(req) => {
805 let roles = inner.gate.roles_listing(&Grant::new(req.grant.clone()));
806 yield AuthEvent::Requires {
807 method: method.into_string(),
808 grant: req.grant,
809 target: req.target,
810 roles: roles.iter().map(|r| r.as_str().to_string()).collect(),
811 public: req.public,
812 };
813 }
814 }
815 }
816 }
817
818 #[plexus_macros::method(group = "admin", description = "Every role and the grants it lists")]
820 async fn roles(&self, auth: &AuthContext) -> impl Stream<Item = AuthEvent> + Send + 'static {
821 let _ = auth;
822 let inner = self.inner.clone();
823 stream! {
824 let admin = RoleName::new(ADMIN);
825 yield role_event(&admin, Some(GrantSet::All));
826 let names: BTreeSet<RoleName> = inner.roles.names().into_iter().filter(|r| r.as_str() != ADMIN).collect();
827 for r in names {
828 let grants = inner.roles.grants(&r);
829 yield role_event(&r, grants);
830 }
831 }
832 }
833
834 #[plexus_macros::method(
837 everywhere,
838 group = "admin",
839 description = "Set a role's grants (admin on *)",
840 params(role = "The role (not admin)", grants = "Grants (tickets.get) or roles to include")
841 )]
842 async fn role_set(&self, auth: &AuthContext, reach: Reach, role: param::RoleName, grants: Vec<param::GrantName>) -> impl Stream<Item = AuthEvent> + Send + 'static {
843 let _ = auth;
844 let inner = self.inner.clone();
845 stream! {
846 if !reach.holds_activation() || reach.grant().is_some_and(|g| g.as_str() != "auth.role_set") {
851 yield needs_everywhere(&inner.gate, "auth.role_set", &reach);
852 return;
853 }
854 if role.as_str() == ADMIN {
857 yield AuthEvent::error("admin holds every grant; it is not edited");
858 return;
859 }
860 let mut set: BTreeSet<Grant> = BTreeSet::new();
861 for entry in grants.iter() {
862 let entry = entry.as_str();
863 if entry.contains('.') {
864 if !inner.catalog.knows(entry) {
865 yield AuthEvent::error(format!("no method {entry} here"));
866 return;
867 }
868 set.insert(Grant::new(entry));
869 } else {
870 match inner.roles.grants(&RoleName::new(entry)) {
871 Some(GrantSet::Listed(included)) => set.extend(included),
872 Some(GrantSet::All) => {
873 yield AuthEvent::error(format!("{entry} holds every grant; a role cannot include it"));
874 return;
875 }
876 None => {
877 yield AuthEvent::error(format!("no role {entry} to include"));
878 return;
879 }
880 }
881 }
882 }
883 let name = role.role();
884 let moving = MovesOnDrop::armed(&inner.gate, GrantsMove::RoleEdit);
885 let set = inner.roles.set(&name, GrantSet::Listed(set)).await;
886 moving.done(set.is_ok());
887 if let Err(e) = set {
888 yield AuthEvent::error(e.0);
889 return;
890 }
891 let now = inner.roles.grants(&name);
892 yield role_event(&name, now);
893 }
894 }
895
896 #[plexus_macros::method(
899 target = "scope",
900 group = "admin",
901 description = "Give a principal a role on a scope",
902 params(principal = "key:…, oidc:…/…, idp:…", role = "The role", scope = "Where: a scope name, or *"),
903 example(note = "make a person an editor on MENGER", params = r#"{"principal": "oidc:workos/user_01M4", "role": "editor", "scope": "MENGER"}"#),
904 example(note = "make an agent's key an admin everywhere", params = r#"{"principal": "key:ac79e0d1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d", "role": "admin", "scope": "*"}"#)
905 )]
906 async fn grant(&self, auth: &AuthContext, reach: Reach, principal: param::Principal, role: param::RoleName, scope: param::ScopeName) -> impl Stream<Item = AuthEvent> + Send + 'static {
907 let inner = self.inner.clone();
908 let caller = auth.clone();
909 stream! {
910 let who: Principal = principal.principal();
911 let role_name = role.role();
912 if role_name.as_str() != ADMIN && inner.roles.grants(&role_name).is_none() {
913 yield AuthEvent::error(format!("no role {role} here"));
914 return;
915 }
916 let scope_ref = match ScopeRef::parse_checked(scope.as_str()) {
921 Ok(s) => s,
922 Err(e) => {
923 yield AuthEvent::error(format!("scope: {e}"));
924 return;
925 }
926 };
927 if let Err(refused) = holds_where_written(&inner.gate, &caller, &reach, "auth.grant", &[scope.as_str(), scope_ref.as_str()]) {
929 yield *refused;
930 return;
931 }
932 let m = Membership { principal: who.clone(), role: role_name.clone(), scope: scope_ref.clone() };
933 match inner.memberships.grant(m).await {
934 Ok(()) => {
935 inner.gate.moved(GrantsMove::Grant);
936 yield AuthEvent::Granted {
937 principal: who.to_string(),
938 role: role_name.as_str().into(),
939 scope: scope_ref.as_str().into(),
940 }
941 }
942 Err(e) => yield AuthEvent::error(e.0),
943 }
944 }
945 }
946
947 #[plexus_macros::method(
949 target = "scope",
950 group = "admin",
951 description = "Take a principal's role on a scope away",
952 params(principal = "key:…, oidc:…/…, idp:…", role = "The role; absent: every role there", scope = "Where: a scope name, or *")
953 )]
954 async fn revoke(&self, auth: &AuthContext, reach: Reach, principal: param::Principal, role: Option<param::RoleName>, scope: param::ScopeName) -> impl Stream<Item = AuthEvent> + Send + 'static {
955 let inner = self.inner.clone();
956 let caller = auth.clone();
957 stream! {
958 let who: Principal = principal.principal();
959 let scope_ref = ScopeRef::parse_checked(scope.as_str()).unwrap_or_else(|_| scope.scope());
962 if let Err(refused) = holds_where_written(&inner.gate, &caller, &reach, "auth.revoke", &[scope.as_str(), scope_ref.as_str()]) {
964 yield *refused;
965 return;
966 }
967 let role_name = role.as_ref().map(param::RoleName::role);
968 let moving = MovesOnDrop::armed(&inner.gate, GrantsMove::Revoke);
969 let revoked = inner.memberships.revoke(&who, role_name.as_ref(), &scope_ref).await;
970 moving.done(revoked.as_ref().is_ok_and(|r| !r.is_empty()));
971 match revoked {
972 Ok(removed) => {
973 yield AuthEvent::Revoked {
974 principal: who.to_string(),
975 scope: scope_ref.as_str().into(),
976 roles: removed.iter().map(|r| r.as_str().to_string()).collect(),
977 }
978 }
979 Err(e) => yield AuthEvent::error(e.0),
980 }
981 }
982 }
983
984 #[plexus_macros::method(everywhere, group = "admin", description = "Who asked for access and holds nothing yet (admin on *)")]
987 async fn waiting(&self, auth: &AuthContext, reach: Reach) -> impl Stream<Item = AuthEvent> + Send + 'static {
988 let _ = auth;
989 let inner = self.inner.clone();
990 stream! {
991 if !reach.holds_activation() || reach.grant().is_some_and(|g| g.as_str() != "auth.waiting") {
994 yield needs_everywhere(&inner.gate, "auth.waiting", &reach);
995 return;
996 }
997 for w in inner.backend.waiting() {
998 let still = w
999 .principal
1000 .parse::<Principal>()
1001 .map(|p| inner.memberships.own_held(&p).is_empty())
1002 .unwrap_or(true);
1003 if still {
1004 yield w.into();
1005 }
1006 }
1007 }
1008 }
1009}
1010
1011#[cfg(test)]
1012mod keel54_body_checks {
1013 use super::super::auth_memory::{MemoryAuthBackend, MemoryMemberships, MemoryRoles};
1017 use super::*;
1018 use crate::plexus::Activation;
1019 use futures::StreamExt;
1020 use plexus_auth_core::grants::{RoleTable, CEILING_KEY};
1021 use serde_json::{json, Value};
1022
1023 const KILN_ADMIN: &str = "key:4b494c4e4b494c4e4b494c4e4b494c4e4b494c4e4b494c4e4b494c4e4b494c4e";
1024 const ADMIN: &str = "key:adadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadad";
1025 const TARGET: &str = "key:7474747474747474747474747474747474747474747474747474747474747474";
1026
1027 struct Kiln;
1028 impl Resolve for Kiln {
1029 fn chain(&self, t: &str) -> Option<Vec<ScopeRef>> {
1030 Some(vec![ScopeRef::named(t.split('-').next().unwrap_or(t)), ScopeRef::Everywhere])
1031 }
1032 }
1033
1034 fn mounted() -> (AuthActivation, Gate, Arc<MemoryMemberships>) {
1035 let members = Arc::new(MemoryMemberships::new().with(KILN_ADMIN, "admin", "KILN").with(ADMIN, "admin", "*"));
1036 let roles = Arc::new(MemoryRoles::new(RoleTable::from_lists([("viewer", ["auth.whoami"])])));
1037 let setup = AuthSetup::new(Arc::new(MemoryAuthBackend::new("http://x/login")), roles, members.clone(), Arc::new(Kiln));
1038 let (auth, gate) = AuthActivation::mount(setup, Catalog::default());
1039 (auth, gate, members)
1040 }
1041
1042 fn who(p: &str, ceiling: Option<&[&str]>) -> AuthContext {
1043 let meta = ceiling.map_or(Value::Null, |c| json!({ CEILING_KEY: c }));
1044 AuthContext::for_principal(&p.parse().unwrap(), "s", vec![], meta)
1045 }
1046
1047 async fn said(auth: &AuthActivation, ctx: &AuthContext, reach: Reach, method: &str, params: Value) -> Value {
1049 let run = async {
1050 let mut stream = Activation::call(auth, method, params, Some(ctx), None).await.expect("dispatched");
1051 stream.next().await.expect("an item")
1052 };
1053 let item = crate::call::scope(crate::call::CallContext::admitted(Some(ctx), reach), run).await;
1054 serde_json::to_value(item).unwrap()["content"].clone()
1055 }
1056
1057 fn everything() -> Value {
1058 json!({ "principal": TARGET, "role": "admin", "scope": "*" })
1059 }
1060
1061 fn raised(members: &MemoryMemberships) -> bool {
1062 members.all().iter().any(|m| m.principal.to_string() == TARGET && m.scope.is_everywhere())
1063 }
1064
1065 #[tokio::test]
1069 async fn an_admin_of_one_scope_granting_everything_is_refused_by_the_method_itself() {
1070 let (auth, gate, members) = mounted();
1071 let ctx = who(KILN_ADMIN, None);
1072 for decided in ["vault.anything", "auth.grant"] {
1073 let reach = gate.check(Some(&ctx), &Grant::new(decided), None).unwrap();
1074 let refused = said(&auth, &ctx, reach, "grant", everything()).await;
1075 assert_eq!((refused["type"].as_str(), refused["error_kind"].as_str()), (Some("error"), Some("forbidden")), "{decided}: {refused}");
1076 assert!(!raised(&members), "{decided}");
1077 }
1078 let reach = gate.check(Some(&ctx), &Grant::new("auth.revoke"), Some("KILN")).unwrap();
1079 let refused = said(&auth, &ctx, reach, "revoke", json!({ "principal": ADMIN, "scope": "*" })).await;
1080 assert_eq!(refused["error_kind"], "forbidden", "{refused}");
1081 assert!(members.all().iter().any(|m| m.principal.to_string() == ADMIN), "nothing was taken");
1082 let reach = gate.check(Some(&ctx), &Grant::new("auth.grant"), Some("KILN")).unwrap();
1084 let granted = said(&auth, &ctx, reach, "grant", json!({ "principal": TARGET, "role": "admin", "scope": "KILN" })).await;
1085 assert_eq!(granted["type"], "granted", "{granted}");
1086 }
1087
1088 #[tokio::test]
1089 async fn a_capped_session_is_held_to_its_cap_by_the_method_itself() {
1090 let (auth, gate, members) = mounted();
1091 let ctx = who(ADMIN, Some(&["admin@KILN"]));
1092 let reach = gate.check(Some(&ctx), &Grant::new("auth.grant"), Some("KILN")).unwrap();
1093 let refused = said(&auth, &ctx, reach.clone(), "grant", everything()).await;
1094 assert_eq!(refused["error_kind"], "forbidden", "{refused}");
1095 assert!(!raised(&members));
1096 let granted = said(&auth, &ctx, reach, "grant", json!({ "principal": TARGET, "role": "viewer", "scope": "KILN-3" })).await;
1097 assert_eq!(granted["type"], "granted", "{granted}");
1098 }
1099
1100 #[tokio::test]
1102 async fn the_admin_of_everything_grants_and_revokes_as_before() {
1103 let (auth, gate, members) = mounted();
1104 let ctx = who(ADMIN, None);
1105 let reach = gate.check(Some(&ctx), &Grant::new("auth.grant"), Some("*")).unwrap();
1106 assert_eq!(said(&auth, &ctx, reach, "grant", everything()).await["type"], "granted");
1107 assert!(raised(&members));
1108 let reach = gate.check(Some(&ctx), &Grant::new("auth.revoke"), Some("self")).unwrap();
1109 let revoked = said(&auth, &ctx, reach, "revoke", json!({ "principal": TARGET, "scope": "self" })).await;
1110 assert_eq!(revoked["type"], "revoked", "{revoked}");
1111 assert!(!raised(&members));
1112 let reach = gate.check(Some(&ctx), &Grant::new("auth.revoke"), Some("*")).unwrap();
1114 assert_eq!(said(&auth, &ctx, reach, "grant", everything()).await["error_kind"], "forbidden");
1115 assert!(!raised(&members));
1116 }
1117}
1118
1119struct MovesOnDrop<'a> {
1126 gate: &'a plexus_auth_core::grants::Gate,
1127 why: Option<GrantsMove>,
1128}
1129
1130impl<'a> MovesOnDrop<'a> {
1131 fn armed(gate: &'a plexus_auth_core::grants::Gate, why: GrantsMove) -> Self {
1132 Self { gate, why: Some(why) }
1133 }
1134
1135 fn done(mut self, changed: bool) {
1137 if let Some(why) = self.why.take().filter(|_| changed) {
1138 self.gate.moved(why);
1139 }
1140 }
1141}
1142
1143impl Drop for MovesOnDrop<'_> {
1144 fn drop(&mut self) {
1145 if let Some(why) = self.why.take() {
1146 self.gate.moved(why);
1147 }
1148 }
1149}