gunnar-grpc 3.0.0

//! `Sso`: company single sign-on, SCIM and the CSV import (see `sso.proto`
//! and [`crate::sso`]).
//!
//! Two kinds of caller. The ACCOUNT ADMIN configures (Admin over the
//! account's namespace — `Accounts.EnrollEmployee`'s rule). The RELAY — the
//! console's own credential, a server admin — hands over what the browser
//! and the IdP said, exactly as it does for `Access.WebLogin`; gunnar verifies
//! it, decides the person and enrols the session key.
//!
//! Every login, every provisioning write and every configuration change is an
//! audit record (the ledger and `gunnar::audit`); no secret — a client
//! secret, a SCIM bearer, a code, a nonce, an assertion — is in any of them.

use std::sync::Arc;

use gunnar_proto::sso_server::Sso;
use gunnar_proto::{
    BeginRequest, BeginResponse, CreateScimTokenRequest, CreateScimTokenResponse, DirectoryUser,
    DiscoverRequest, DiscoverResponse, FinishRequest, FinishResponse, GetProviderRequest,
    GetProviderResponse, GrantLevel, ImportStatusRequest, ImportUsersRequest, ImportUsersResponse,
    ListDirectoryRequest, ListDirectoryResponse, ListScimTokensRequest, ListScimTokensResponse,
    ProviderView, RebindUsersRequest, RebindUsersResponse, RemoveProviderRequest,
    RemoveProviderResponse, RevokeScimTokenRequest, RevokeScimTokenResponse, ScimRequest,
    ScimResponse, SecondFactorNeed, SecondFactorRequest, SecondFactorResponse, SetProviderRequest,
    SetProviderResponse, SetUserActiveRequest, SetUserActiveResponse, SsoProtocol, SsoProvider,
    VerifyDomainRequest, VerifyDomainResponse,
};
use tonic::{Request, Response, Status};

use crate::auth::{Access as Scope, AuditRecord, Caller, AUDIT_TARGET};
use crate::service::SsoService;
use crate::sso::directory::{normalize_domain, normalize_user_name};
use crate::sso::plane::{Room, SecretChange, SsoLoginAsk, SsoPlane, UserPatch};
use crate::sso::{oidc, saml, scim, Second, SCIM_PER_MINUTE, SECOND_TTL_MS};

fn now_ms() -> i64 {
    crate::bus::now_unix_ms()
}

fn account_of(raw: &str) -> Result<String, Status> {
    let account = raw.trim();
    if account.is_empty() || account.len() > 128 || account.contains('/') {
        return Err(Status::invalid_argument(
            "`account` is required (an account name)",
        ));
    }
    Ok(account.to_owned())
}

fn origin_ok(origin: &str, loopback: bool) -> bool {
    let o = origin.trim().trim_end_matches('/');
    let rest = if let Some(r) = o.strip_prefix("https://") {
        r
    } else if loopback {
        match o.strip_prefix("http://") {
            Some(r) => r,
            None => return false,
        }
    } else {
        return false;
    };
    !rest.is_empty() && !rest.contains(['/', '?', '#', '@', ' '])
}

fn same_origin(a: &str, b: &str) -> bool {
    a.trim()
        .trim_end_matches('/')
        .eq_ignore_ascii_case(b.trim().trim_end_matches('/'))
}

fn protocol_of(p: &SsoProvider) -> SsoProtocol {
    SsoProtocol::try_from(p.protocol).unwrap_or(SsoProtocol::Unspecified)
}

fn hash(secret: &str) -> String {
    crate::webauthn::sha256_hex(secret.as_bytes())
}

/// A list of names an admin typed: trimmed, deduplicated, each `[A-Za-z0-9_:./-]`.
fn tokens(list: &[String], what: &str, most: usize) -> Result<Vec<String>, Status> {
    let mut out: Vec<String> = Vec::new();
    for raw in list {
        let t = raw.trim();
        if t.is_empty() {
            continue;
        }
        if t.len() > 256
            || !t
                .bytes()
                .all(|b| b.is_ascii_alphanumeric() || b"_:./-".contains(&b))
        {
            return Err(Status::invalid_argument(format!(
                "{what} {t:?} is not a plain name"
            )));
        }
        if !out.iter().any(|o| o == t) {
            out.push(t.to_owned());
        }
    }
    if out.len() > most {
        return Err(Status::invalid_argument(format!("at most {most} {what}s")));
    }
    Ok(out)
}

/// **The account's own IdP CA for this save** (owner 2026-10-06): pasted —
/// judged and set; not resent — the stored one kept; cleared on ask. Answers
/// the CA (DER) and the audit detail (` idp_ca=<fingerprints> (<change>)`).
/// One CA per account (`OidcSettings.idp_ca_pem`, the one CA field): an OIDC
/// provider's calls trust it, and so does a SAML provider's metadata fetch
/// (A34-41).
fn idp_ca_for(
    stored: Option<&SsoProvider>,
    pasted: &str,
    clear: bool,
) -> Result<(Vec<Vec<u8>>, String), Status> {
    let stored_ca = stored
        .and_then(|p| p.oidc.as_ref())
        .map(oidc::ca_of)
        .unwrap_or_default();
    let (ca, change) = match (clear, pasted.trim()) {
        (true, _) => (Vec::new(), "cleared"),
        (false, "") => (stored_ca, "kept"),
        (false, pem) => (
            crate::sso::idp_ca::parse_idp_ca(pem, now_ms())
                .map_err(|why| Status::invalid_argument(format!("the IdP CA: {why}")))?,
            "set",
        ),
    };
    let said = format!(
        " idp_ca={} ({change})",
        if ca.is_empty() {
            "none".to_owned()
        } else {
            ca.iter()
                .map(|d| saml::fingerprint(d))
                .collect::<Vec<_>>()
                .join(",")
        }
    );
    Ok((ca, said))
}

/// `field` as sent, or — sent empty — the stored one (A34-22, A34-48: what
/// the page does not resend is kept).
fn or_stored(field: &str, stored: Option<&str>) -> String {
    match field.trim() {
        "" => stored.unwrap_or_default().to_owned(),
        sent => sent.to_owned(),
    }
}

fn claim_name(raw: &str, what: &str) -> Result<String, Status> {
    let t = raw.trim();
    if t.len() > 256 || t.chars().any(char::is_control) {
        return Err(Status::invalid_argument(format!(
            "{what} is not a claim or attribute name"
        )));
    }
    Ok(t.to_owned())
}

impl SsoService {
    fn plane(&self) -> Result<&dyn SsoPlane, Status> {
        self.ctx.control.sso().ok_or_else(|| {
            Status::unimplemented(
                "single sign-on needs an identity table; this control plane has none",
            )
        })
    }

    /// The account admin's door. Authenticated FIRST (an unauthenticated
    /// caller is UNAUTHENTICATED whatever the request says), then the account
    /// read out of the request, then the account-admin rule.
    /// [`Self::admin`], and **a fresh user-verified touch** (A34-10): the
    /// caller's identity-core session stepped up (a user-verified touch of
    /// their own passkey) within the window. A stolen admin session cannot point the account at a
    /// hostile IdP, drop it, mint a SCIM bearer or import a directory. Refused
    /// with `[stepup]`, which the console answers with a touch in place.
    fn admin_stepped_up<T>(
        &self,
        request: &Request<T>,
        account: impl FnOnce(&T) -> &str,
        method: &'static str,
    ) -> Result<(Caller, String), Status> {
        let (caller, account) = self.admin(request, account, method)?;
        if !crate::auth::stepped_up(request) {
            self.audit(
                method,
                &caller.principal_id,
                &account,
                false,
                "sso.step_up_refused",
                "[stepup] no fresh user-verified touch",
            );
            return Err(Status::permission_denied(format!(
                "[stepup] {method} needs a fresh touch of your own passkey (user-verified, within the last \
                 10 minutes)"
            )));
        }
        Ok((caller, account))
    }

    fn admin<T>(
        &self,
        request: &Request<T>,
        account: impl FnOnce(&T) -> &str,
        method: &'static str,
    ) -> Result<(Caller, String), Status> {
        let caller = self.ctx.caller(request)?;
        let account = account_of(account(request.get_ref()))?;
        self.ctx
            .require(
                &caller,
                Scope::namespace(&account),
                GrantLevel::Admin,
                method,
            )
            .map_err(|status| {
                crate::service::repos::account_admin_only_for(
                    status,
                    &account,
                    "the identity provider and directory of account",
                )
            })?;
        // **A clan is no account** (clans + SSO, 2026-10-05). A clan's admin
        // holds Admin over the clan's namespace — the rule above — but an
        // identity provider, a SCIM bearer or an import there would make the
        // people they let in EMPLOYEES of the clan, and a clan's members are
        // accounts of their own. Refused as `Accounts.EnrollEmployee` refuses
        // it, and only after the admin rule, so an outsider learns nothing
        // about the name.
        if let Some(clans) = self.ctx.control.clans() {
            if clans.clan_get(&account)?.is_some() {
                return Err(Status::failed_precondition(format!(
                    "{account} is a clan, not an account: a clan has no identity provider, \
                     SCIM bearer or directory — its members are accounts of their own, and \
                     each account's admin configures its own"
                )));
            }
        }
        Ok((caller, account))
    }

    /// The relay's door: the console's own credential.
    fn relay<T>(&self, request: &Request<T>, method: &'static str) -> Result<Caller, Status> {
        self.ctx
            .authorize(request, Scope::Server, GrantLevel::Admin, method)
    }

    /// One audit record: the ledger, and `gunnar::audit`.
    fn audit(
        &self,
        method: &'static str,
        principal: &str,
        account: &str,
        allowed: bool,
        event: &'static str,
        reason: &str,
    ) {
        let scope = format!("account:{account}");
        if let Some(ledger) = self.ctx.audit.as_deref() {
            ledger.record(AuditRecord {
                method,
                principal,
                fingerprint: "",
                scope: &scope,
                level: "",
                auth_mode: self.ctx.config.auth.as_str(),
                decision: if allowed { "allow" } else { "deny" },
                reason,
            });
        }
        if allowed {
            tracing::info!(target: AUDIT_TARGET, event, method, principal, account, reason, "single sign-on");
        } else {
            tracing::warn!(target: AUDIT_TARGET, event, method, principal, account, reason, "single sign-on refused");
        }
        // **The ACCOUNT's own log** (the owner's enterprise list, 2026-10-05):
        // every step of its single sign-on is its admin's to read — a sign-in
        // is a `login` like a passkey's, a SCIM or CSV change is its member's.
        if !account.is_empty() {
            let (kind, target) = match event {
                "sso.login" | "sso.login_refused" => ("login", "sso"),
                "sso.second_factor" | "sso.second_factor_refused" => ("login.second_factor", "sso"),
                "sso.user_deactivated" => ("member.deactivated", "sso"),
                "sso.user_reactivated" => ("member.reactivated", "sso"),
                "sso.scim" | "sso.scim_refused" => ("member.scim", "scim"),
                "sso.csv_import" => ("member.imported", "csv"),
                other => (other, "sso"),
            };
            self.ctx.account_event(
                Some(account.to_owned()),
                crate::enterprise::AccountAuditEvent {
                    kind: kind.to_owned(),
                    actor: principal.to_owned(),
                    actor_machine: false,
                    target: target.to_owned(),
                    detail: reason.to_owned(),
                    refused: !allowed,
                },
            );
        }
    }

    fn room(&self, account: &str) -> Result<Room, Status> {
        let (cap, stored) = match crate::service::accounts::account_room(&self.ctx, account)? {
            Some((cap, stored)) => (Some(cap), stored),
            None => (None, 0),
        };
        Ok(Room {
            room_bytes: crate::service::accounts::ROOM_PER_USER_BYTES,
            cap,
            stored,
        })
    }

    /// The provider as an answer: secrets never, certificates as fingerprints.
    fn view(&self, provider: SsoProvider) -> ProviderView {
        let mut shown = provider.clone();
        if let Some(s) = shown.saml.as_mut() {
            s.idp_certificates = saml::certificates(s)
                .unwrap_or_default()
                .iter()
                .map(|der| saml::fingerprint(der))
                .collect();
            s.idp_metadata_xml.clear();
        }
        // The account's IdP CA: its fingerprints, never the certificates.
        if let Some(o) = shown.oidc.as_mut() {
            o.idp_ca_fingerprints = oidc::ca_of(o)
                .iter()
                .map(|d| saml::fingerprint(d))
                .collect();
            o.idp_ca_pem.clear();
        }
        let origin = provider.console_origin.clone();
        let is_saml = protocol_of(&provider) == SsoProtocol::Saml;
        ProviderView {
            redirect_uri: oidc::gunnar_core_paths::redirect_uri(&origin),
            sp_entity_id: oidc::gunnar_core_paths::sp_entity_id(&origin, &provider.account),
            acs_url: oidc::gunnar_core_paths::acs_url(&origin),
            sp_metadata_xml: if is_saml {
                saml::sp_metadata(&provider)
            } else {
                String::new()
            },
            domain_proofs: provider
                .domains
                .iter()
                .map(|d| gunnar_proto::DomainProof {
                    domain: d.clone(),
                    txt_name: crate::sso::domains::txt_name(d),
                    txt_value: crate::sso::domains::proof_value(&provider.account, d),
                    verified: provider.verified_domains.contains(d),
                })
                .collect(),
            provider: Some(shown),
        }
    }

    fn directory_user(user: crate::sso::plane::DirUser) -> DirectoryUser {
        user.user
    }
}

/// Why no domain proof is read on a box fed no resolver (RA5-24).
pub const NO_RESOLVER: &str = "feed sso_dns_resolver: no DNS-over-HTTPS resolver is named for domain proofs, and none is dialled by default (the operator names the one this box may ask)";

#[tonic::async_trait]
impl Sso for SsoService {
    /// **Configure the account's identity provider** — the account admin's.
    async fn set_provider(
        &self,
        request: Request<SetProviderRequest>,
    ) -> Result<Response<SetProviderResponse>, Status> {
        const METHOD: &str = "Sso.SetProvider";
        let (caller, account) = self.admin_stepped_up(
            &request,
            |r: &SetProviderRequest| r.provider.as_ref().map_or("", |p| p.account.as_str()),
            METHOD,
        )?;
        let input = request
            .get_ref()
            .provider
            .clone()
            .ok_or_else(|| Status::invalid_argument("`provider` is required"))?;
        let plane = self.plane()?;
        let request = request.into_inner();
        let loopback = self.ctx.sso.allow_loopback_http();
        let protocol = protocol_of(&input);
        if !origin_ok(&input.console_origin, loopback) {
            return Err(Status::invalid_argument(
                "`console_origin` is the console's https origin (https://host[:port])",
            ));
        }
        let display_name = match input.display_name.trim() {
            "" => account.clone(),
            d if d.chars().count() <= 80 && !d.chars().any(char::is_control) => d.to_owned(),
            _ => {
                return Err(Status::invalid_argument(
                    "`display_name` is at most 80 printable characters",
                ))
            }
        };
        let mut domains = Vec::new();
        for raw in &input.domains {
            if raw.trim().is_empty() {
                continue;
            }
            let d = normalize_domain(raw).ok_or_else(|| {
                Status::invalid_argument(format!("{raw:?} is not an email domain"))
            })?;
            // A public mail domain leads to no company (A34-5).
            crate::sso::domains::admissible(&d)
                .map_err(|r| Status::invalid_argument(r.message()))?;
            if !domains.contains(&d) {
                domains.push(d);
            }
        }
        if domains.len() > 20 {
            return Err(Status::invalid_argument("at most 20 domains"));
        }
        let stored = plane.provider(&account)?;
        let mut provider = SsoProvider {
            account: account.clone(),
            protocol: protocol as i32,
            display_name,
            domains,
            oidc: None,
            saml: None,
            require_sso: input.require_sso,
            require_passkey: input.require_passkey,
            console_origin: input.console_origin.trim().trim_end_matches('/').to_owned(),
            has_client_secret: false,
            updated_at_unix_ms: now_ms(),
            updated_by: caller.principal_id.clone(),
            verified_domains: Vec::new(),
            jit: input.jit,
        };
        let secret;
        let ca_said;
        match protocol {
            SsoProtocol::Oidc => {
                let o = input
                    .oidc
                    .clone()
                    .ok_or_else(|| Status::invalid_argument("an OIDC provider needs `oidc`"))?;
                let issuer = o.issuer.trim().trim_end_matches('/').to_owned();
                crate::sso::url_allowed_in(
                    &oidc::discovery_url(&issuer),
                    loopback,
                    &self.ctx.sso.private_nets(),
                )
                .map_err(|why| Status::invalid_argument(format!("the issuer: {why}")))?;
                // **The account's own IdP CA**: trusted for THIS provider's calls alone.
                let (ca, said) = idp_ca_for(stored.as_ref(), &o.idp_ca_pem, request.clear_idp_ca)?;
                ca_said = said;
                let stored_oidc = stored.as_ref().and_then(|p| p.oidc.as_ref());
                let client_id = o.client_id.trim().to_owned();
                if client_id.is_empty() || client_id.len() > 512 {
                    return Err(Status::invalid_argument("the client id is required"));
                }
                provider.oidc = Some(gunnar_proto::OidcSettings {
                    issuer: issuer.clone(),
                    client_id,
                    scopes: tokens(&o.scopes, "scope", 20)?,
                    username_claim: claim_name(&o.username_claim, "the user-name claim")?,
                    // Not on the page: sent empty, the stored one is kept (A34-48).
                    display_name_claim: claim_name(
                        &or_stored(
                            &o.display_name_claim,
                            stored_oidc.map(|s| s.display_name_claim.as_str()),
                        ),
                        "the display-name claim",
                    )?,
                    idp_ca_pem: crate::sso::idp_ca::idp_ca_pem(&ca),
                    idp_ca_fingerprints: Vec::new(),
                });
                secret = match (request.clear_client_secret, request.client_secret.trim()) {
                    (true, _) => SecretChange::Clear,
                    (false, "") => SecretChange::Keep,
                    (false, s) if s.len() > 4096 => {
                        return Err(Status::invalid_argument(
                            "the client secret is longer than 4 KiB",
                        ))
                    }
                    (false, s) => SecretChange::Set(s.to_owned()),
                };
                // The issuer is read once now, so a typo is said to the admin
                // here and not to every employee at the login page.
                // Only while the operator turned SSO's network on (A34-16); an airgap box
                // stores the provider unread, and its sign-ins are refused by name.
                if let Ok(egress) = self.ctx.sso.egress() {
                    oidc::idp(&self.ctx.sso, egress, &issuer, &ca, now_ms(), true)
                        .await
                        .map_err(|why| {
                            Status::failed_precondition(format!(
                                "the issuer could not be read: {why}"
                            ))
                        })?;
                }
            }
            SsoProtocol::Saml => {
                let s = input
                    .saml
                    .clone()
                    .ok_or_else(|| Status::invalid_argument("a SAML provider needs `saml`"))?;
                let mut s = s;
                let stored_saml = stored.as_ref().and_then(|p| p.saml.as_ref());
                // What the admin did not resend is the stored one (A34-22: the
                // page cannot send the XML back, nor the certificates — an
                // answer shows fingerprints, never the certificate): with no
                // metadata in this save, the stored entity id, sign-on URL and
                // certificates stand, so the toggles can be saved alone.
                let no_metadata =
                    s.idp_metadata_xml.trim().is_empty() && s.idp_metadata_url.trim().is_empty();
                if no_metadata {
                    s.idp_entity_id = or_stored(
                        &s.idp_entity_id,
                        stored_saml.map(|p| p.idp_entity_id.as_str()),
                    );
                    s.idp_sso_url =
                        or_stored(&s.idp_sso_url, stored_saml.map(|p| p.idp_sso_url.as_str()));
                }
                let keep_certs =
                    s.idp_certificates.iter().all(|c| c.starts_with("SHA256:")) && no_metadata;
                if keep_certs {
                    s.idp_certificates = stored_saml.map(|p| {
                        p.idp_certificates.iter().map(|b64| format!("-----BEGIN CERTIFICATE-----\n{b64}\n-----END CERTIFICATE-----")).collect()
                    }).unwrap_or_default();
                }
                // The account's IdP CA (A34-41): the metadata URL is read
                // trusting it, as an OIDC provider's calls are.
                let pasted = input.oidc.as_ref().map_or("", |o| o.idp_ca_pem.as_str());
                let (ca, said) = idp_ca_for(stored.as_ref(), pasted, request.clear_idp_ca)?;
                ca_said = said;
                let egress = self
                    .ctx
                    .sso
                    .egress()
                    .ok()
                    .map(|e| saml::trusting(e, ca.clone()));
                let mut resolved = saml::resolve_input(&self.ctx.sso, egress, &s)
                    .await
                    .map_err(Status::invalid_argument)?;
                // Not on the page: sent empty, the stored one is kept (A34-48).
                resolved.display_name_attribute = or_stored(
                    &resolved.display_name_attribute,
                    stored_saml.map(|p| p.display_name_attribute.as_str()),
                );
                provider.saml = Some(resolved);
                // A SAML provider keeps the account's CA in the one CA field.
                provider.oidc = (!ca.is_empty()).then(|| gunnar_proto::OidcSettings {
                    idp_ca_pem: crate::sso::idp_ca::idp_ca_pem(&ca),
                    ..Default::default()
                });
                secret = SecretChange::Clear;
            }
            SsoProtocol::Unspecified => {
                return Err(Status::invalid_argument("`protocol` is OIDC or SAML"))
            }
        }
        let saved = plane
            .set_provider(provider, secret, &caller.principal_id)
            .map_err(|err| {
                self.audit(
                    METHOD,
                    &caller.principal_id,
                    &account,
                    false,
                    "sso.provider_refused",
                    &err.to_string(),
                );
                Status::from(err)
            })?;
        self.audit(
            METHOD,
            &caller.principal_id,
            &account,
            true,
            "sso.provider_set",
            &format!(
                "protocol={} require_sso={} require_passkey={} domains={}{ca_said}",
                if protocol == SsoProtocol::Oidc {
                    "oidc"
                } else {
                    "saml"
                },
                saved.require_sso,
                saved.require_passkey,
                saved.domains.join(",")
            ),
        );
        Ok(Response::new(SetProviderResponse {
            view: Some(self.view(saved)),
        }))
    }

    async fn get_provider(
        &self,
        request: Request<GetProviderRequest>,
    ) -> Result<Response<GetProviderResponse>, Status> {
        let (_, account) = self.admin(&request, |r| r.account.as_str(), "Sso.GetProvider")?;
        let view = self.plane()?.provider(&account)?.map(|p| self.view(p));
        // A34-47: the addresses are gunnar's, for the console's origin, so the
        // console renders them and builds none.
        let origin = request
            .get_ref()
            .console_origin
            .trim()
            .trim_end_matches('/')
            .to_owned();
        let addresses = if origin.is_empty() {
            None
        } else if origin_ok(&origin, self.ctx.sso.allow_loopback_http()) {
            use oidc::gunnar_core_paths as paths;
            Some(gunnar_proto::ConsoleAddresses {
                redirect_uri: paths::redirect_uri(&origin),
                sp_entity_id: paths::sp_entity_id(&origin, &account),
                acs_url: paths::acs_url(&origin),
                login_url: paths::login_url(&origin, &account),
                scim_base_url: paths::scim_base_url(&origin),
            })
        } else {
            return Err(Status::invalid_argument(format!(
                "`console_origin` {origin:?} is not an https origin"
            )));
        };
        Ok(Response::new(GetProviderResponse { view, addresses }))
    }

    async fn remove_provider(
        &self,
        request: Request<RemoveProviderRequest>,
    ) -> Result<Response<RemoveProviderResponse>, Status> {
        const METHOD: &str = "Sso.RemoveProvider";
        let (caller, account) = self.admin_stepped_up(&request, |r| r.account.as_str(), METHOD)?;
        let removed = self.plane()?.remove_provider(&account)?;
        self.audit(
            METHOD,
            &caller.principal_id,
            &account,
            true,
            "sso.provider_removed",
            if removed { "removed" } else { "there was none" },
        );
        Ok(Response::new(RemoveProviderResponse { removed }))
    }

    async fn create_scim_token(
        &self,
        request: Request<CreateScimTokenRequest>,
    ) -> Result<Response<CreateScimTokenResponse>, Status> {
        const METHOD: &str = "Sso.CreateScimToken";
        let (caller, account) = self.admin_stepped_up(&request, |r| r.account.as_str(), METHOD)?;
        let label = request
            .get_ref()
            .label
            .trim()
            .chars()
            .take(128)
            .collect::<String>();
        // A34-27: an optional expiry (at most a year) and a read-only scope.
        let expires = scim::bearer::expiry_of(request.get_ref().expires_in_days, now_ms())
            .map_err(Status::invalid_argument)?;
        let read_only = request.get_ref().read_only;
        let secret = format!(
            "gscim_{}",
            crate::webauthn::b64url(&crate::webauthn::random_bytes(32))
        );
        let id = crate::webauthn::hex(&crate::webauthn::random_bytes(8));
        let token = self.plane()?.create_scim_token(
            &account,
            &id,
            &label,
            &hash(&secret),
            &caller.principal_id,
            expires,
            read_only,
        )?;
        self.audit(
            METHOD,
            &caller.principal_id,
            &account,
            true,
            "sso.scim_token_created",
            &format!(
                "token={id} scope={} expires={}",
                if read_only { "read" } else { "read-write" },
                if expires == 0 {
                    "never".to_owned()
                } else {
                    crate::sso::rfc3339(expires / 1000)
                }
            ),
        );
        Ok(Response::new(CreateScimTokenResponse {
            token: Some(token),
            secret,
        }))
    }

    async fn list_scim_tokens(
        &self,
        request: Request<ListScimTokensRequest>,
    ) -> Result<Response<ListScimTokensResponse>, Status> {
        let (_, account) = self.admin(&request, |r| r.account.as_str(), "Sso.ListScimTokens")?;
        let now = now_ms();
        let tokens = self
            .plane()?
            .scim_tokens(&account)?
            .into_iter()
            .map(|mut t| {
                // A34-27: a bearer unused for long, expiring or expired is
                // flagged on the admin's list.
                t.attention = scim::bearer::needs_attention(
                    t.created_at_unix_ms,
                    t.last_used_unix_ms,
                    t.expires_at_unix_ms,
                    now,
                )
                .unwrap_or_default()
                .to_owned();
                t
            })
            .collect();
        Ok(Response::new(ListScimTokensResponse { tokens }))
    }

    async fn revoke_scim_token(
        &self,
        request: Request<RevokeScimTokenRequest>,
    ) -> Result<Response<RevokeScimTokenResponse>, Status> {
        const METHOD: &str = "Sso.RevokeScimToken";
        let (caller, account) = self.admin(&request, |r| r.account.as_str(), METHOD)?;
        let id = request.get_ref().token_id.trim().to_owned();
        let revoked = self.plane()?.revoke_scim_token(&account, &id)?;
        self.audit(
            METHOD,
            &caller.principal_id,
            &account,
            true,
            "sso.scim_token_revoked",
            &format!("token={id} revoked={revoked}"),
        );
        Ok(Response::new(RevokeScimTokenResponse { revoked }))
    }

    async fn list_directory(
        &self,
        request: Request<ListDirectoryRequest>,
    ) -> Result<Response<ListDirectoryResponse>, Status> {
        let (_, account) = self.admin(&request, |r| r.account.as_str(), "Sso.ListDirectory")?;
        let plane = self.plane()?;
        let users = plane
            .directory(&account)?
            .into_iter()
            .filter(|u| !u.deleted)
            .map(Self::directory_user)
            .collect();
        let groups = plane.groups(&account)?.len() as u32;
        Ok(Response::new(ListDirectoryResponse { users, groups }))
    }

    async fn set_user_active(
        &self,
        request: Request<SetUserActiveRequest>,
    ) -> Result<Response<SetUserActiveResponse>, Status> {
        const METHOD: &str = "Sso.SetUserActive";
        let (caller, account) = self.admin(&request, |r| r.account.as_str(), METHOD)?;
        let request = request.into_inner();
        let (user, changed) = self.plane()?.update_user(
            &account,
            request.principal_id.trim(),
            UserPatch {
                active: Some(request.active),
                ..UserPatch::default()
            },
            &caller.principal_id,
        )?;
        self.audit(
            METHOD,
            &caller.principal_id,
            &account,
            true,
            if request.active {
                "sso.user_reactivated"
            } else {
                "sso.user_deactivated"
            },
            &format!("employee={} changed={changed}", user.user.principal_id),
        );
        Ok(Response::new(SetUserActiveResponse {
            user: Some(Self::directory_user(user)),
        }))
    }

    /// **The CSV import, as a background job** (A34-17): checked here (the
    /// account admin with a fresh touch, the size), then queued on the
    /// server's jera lane; the whole file is applied in one write or not at
    /// all, and the answer is the job as it stands (`Sso.ImportStatus`
    /// follows it).
    async fn import_users(
        &self,
        request: Request<ImportUsersRequest>,
    ) -> Result<Response<ImportUsersResponse>, Status> {
        const METHOD: &str = "Sso.ImportUsers";
        let (caller, account) = self.admin_stepped_up(&request, |r| r.account.as_str(), METHOD)?;
        let request = request.into_inner();
        // A34-44: the one limit, refused by name before anything is queued.
        if request.csv.len() > crate::sso::directory::CSV_MAX_BYTES {
            return Err(Status::invalid_argument(crate::sso::directory::too_large()));
        }
        self.plane()?;
        let room = self.room(&account)?;
        let audit = {
            let me = self.clone();
            let principal = caller.principal_id.clone();
            let account = account.clone();
            let dry_run = request.dry_run;
            Arc::new(move |done: &Result<scim::Imported, String>| {
                if dry_run {
                    return;
                }
                match done {
                    Ok(done) => me.audit(
                        METHOD,
                        &principal,
                        &account,
                        true,
                        "sso.csv_import",
                        &format!(
                            "created={} updated={} deactivated={} reactivated={} errors={}",
                            done.created,
                            done.updated,
                            done.deactivated,
                            done.reactivated,
                            done.errors.len()
                        ),
                    ),
                    Err(why) => {
                        me.audit(METHOD, &principal, &account, false, "sso.csv_import", why)
                    }
                }
            })
        };
        let job = self.ctx.control.sso_import(scim::ImportOrder {
            account: account.clone(),
            csv: Arc::from(request.csv.as_str()),
            dry_run: request.dry_run,
            room,
            actor: format!("csv:{}", caller.principal_id),
            plane: Arc::downgrade(&self.ctx.control),
            finished: audit,
        })?;
        Ok(Response::new(import_answer(job, request.dry_run)))
    }

    /// **Where the account's import job is** — the account admin's.
    async fn import_status(
        &self,
        request: Request<ImportStatusRequest>,
    ) -> Result<Response<ImportUsersResponse>, Status> {
        let (_, account) = self.admin(&request, |r| r.account.as_str(), "Sso.ImportStatus")?;
        let wanted = request.get_ref().job_id.trim().to_owned();
        match self.ctx.control.sso_import_status(&account)? {
            Some(job) if wanted.is_empty() || job.job_id == wanted => {
                let dry_run = job.outcome.dry_run;
                Ok(Response::new(import_answer(job, dry_run)))
            }
            _ => Err(Status::not_found(format!(
                "no import job {wanted} for account {account} (a finished job is kept ten minutes)"
            ))),
        }
    }

    /// The login page's "Sign in with <company>" — the relay's.
    async fn discover(
        &self,
        request: Request<DiscoverRequest>,
    ) -> Result<Response<DiscoverResponse>, Status> {
        self.relay(&request, "Sso.Discover")?;
        let plane = self.plane()?;
        // Whether the login page offers the company field at all (round 5.3):
        // on every answer, the empty hint's included. It names no account.
        let any_provider = plane.any_provider()?;
        let hint = request.get_ref().hint.trim().to_ascii_lowercase();
        if hint.is_empty() || hint.len() > 320 {
            return Ok(Response::new(DiscoverResponse {
                any_provider,
                ..Default::default()
            }));
        }
        // **Proven domains only** (A34-39, A34-5): an address or a domain finds
        // the account that proved the domain by DNS; an account name, or a domain
        // nobody proved, finds nothing, so Discover lists no account.
        let domain = hint.rsplit_once('@').map_or(hint.as_str(), |(_, d)| d);
        let account = match normalize_domain(domain) {
            Some(d) => plane.account_for_domain(&d)?,
            None => None,
        };
        let found = match account {
            Some(a) if !a.contains('/') => plane.provider(&a)?,
            _ => None,
        };
        Ok(Response::new(match found {
            Some(p) => DiscoverResponse {
                found: true,
                account: p.account.clone(),
                display_name: p.display_name.clone(),
                protocol: p.protocol,
                any_provider,
            },
            None => DiscoverResponse {
                any_provider,
                ..Default::default()
            },
        }))
    }

    /// **Begin a sign-in** — the relay's.
    async fn begin(
        &self,
        request: Request<BeginRequest>,
    ) -> Result<Response<BeginResponse>, Status> {
        const METHOD: &str = "Sso.Begin";
        self.relay(&request, METHOD)?;
        let request = request.into_inner();
        let account = account_of(&request.account)?;
        let plane = self.plane()?;
        let now = now_ms();
        // Counted per (account, client) (A34-6): one address at its limit never holds
        // back another address of the same account.
        let client = nornir_identity_sso::client_key(&request.client);
        if !self.ctx.sso.allow_begin(&account, &client, now) {
            self.audit(
                METHOD,
                "",
                &account,
                false,
                "sso.rate_limited",
                "too many sign-ins begun this minute",
            );
            return Err(Status::resource_exhausted(format!(
                "[sso-busy] too many sign-ins to {account} from this address this minute; try again shortly"
            )));
        }
        let provider = plane
            .provider(&account)?
            .ok_or_else(|| Status::not_found(format!("{account} has no single sign-on")))?;
        if !same_origin(&request.console_origin, &provider.console_origin) {
            return Err(Status::failed_precondition(format!(
                "{account}'s single sign-on is configured for {}, not for this console",
                provider.console_origin
            )));
        }
        let (url, state, flow) = match protocol_of(&provider) {
            SsoProtocol::Oidc => {
                // Refused by name while the operator has not turned SSO's network on (A34-16).
                let egress = self.ctx.sso.egress().map_err(Status::unavailable)?;
                oidc::begin(
                    &self.ctx.sso,
                    egress,
                    &provider,
                    request.login_hint.trim(),
                    now,
                )
                .await
                .map_err(|why| {
                    Status::unavailable(format!("{account}'s identity provider: {why}"))
                })?
            }
            SsoProtocol::Saml => {
                saml::begin(&provider, now).map_err(Status::failed_precondition)?
            }
            SsoProtocol::Unspecified => {
                return Err(Status::failed_precondition(
                    "the provider names no protocol",
                ))
            }
        };
        let expires = flow.expires_ms;
        let flow = crate::sso::Flow { client, ..flow };
        self.ctx
            .sso
            .begin(hash(&state), flow, now)
            .map_err(Status::resource_exhausted)?;
        tracing::info!(target: AUDIT_TARGET, event = "sso.begin", account = %account, "a single sign-on began");
        Ok(Response::new(BeginResponse {
            redirect_url: url,
            state,
            expires_at_unix_ms: expires,
            protocol: provider.protocol,
        }))
    }

    /// **Finish a sign-in** — the relay's: verified, mapped, enrolled.
    async fn finish(
        &self,
        request: Request<FinishRequest>,
    ) -> Result<Response<FinishResponse>, Status> {
        const METHOD: &str = "Sso.Finish";
        self.relay(&request, METHOD)?;
        let request = request.into_inner();
        let now = now_ms();
        // Spent FIRST, whatever happens next: a state is single use.
        let flow = self
            .ctx
            .sso
            .take_flow(&hash(request.state.trim()), now)
            .ok_or_else(|| {
                Status::permission_denied(nornir_identity_sso::Refusal::Expired.message())
            })?;
        let account = flow.account.clone();
        // The client finishing (the one that began, when the relay names none): its
        // failures hold back that client alone (A34-6).
        let client = match request.client.trim() {
            "" => flow.client.clone(),
            named => nornir_identity_sso::client_key(named),
        };
        let refuse = |why: String| {
            // Every refusal carries its code (A34-46); a protocol's own words are
            // the IdP's refusal.
            let why = match nornir_identity_sso::code_of(&why) {
                Some(_) => why,
                None => nornir_identity_sso::Refusal::IdpRefused.with(&why),
            };
            self.ctx.sso.note_failure(&account, &client, now);
            self.audit(METHOD, "", &account, false, "sso.login_refused", &why);
            Status::permission_denied(format!("single sign-on refused: {why}"))
        };
        if self.ctx.sso.failures_held(&account, &client, now) {
            self.audit(
                METHOD,
                "",
                &account,
                false,
                "sso.rate_limited",
                "too many failed sign-ins this minute",
            );
            return Err(Status::resource_exhausted(
                "[sso-busy] too many failed sign-ins to this account from this address this minute; try again shortly",
            ));
        }
        if !same_origin(&request.console_origin, &flow.console_origin) {
            return Err(refuse(nornir_identity_sso::Refusal::OtherConsole.message()));
        }
        if !request.idp_error.trim().is_empty() {
            let said: String = request.idp_error.trim().chars().take(100).collect();
            return Err(refuse(format!("the identity provider said {said:?}")));
        }
        let identity = self.ctx.identity.clone().ok_or_else(|| {
            Status::unavailable("this server serves no identity core, so it signs nobody in")
        })?;
        let plane = self.plane()?;
        let provider = match plane.provider(&account)? {
            Some(p) if same_origin(&p.console_origin, &flow.console_origin) => p,
            _ => {
                return Err(refuse(
                    nornir_identity_sso::Refusal::ProviderChanged.message(),
                ))
            }
        };
        let protocol = protocol_of(&provider);
        let (issuer, subject, user_name, display_name, email, email_verified, idp_ids) =
            match (protocol, flow.saml) {
                (SsoProtocol::Oidc, false) => {
                    // Refused by name while the operator has not turned SSO's network on (A34-16).
                    let egress = self.ctx.sso.egress().map_err(Status::unavailable)?;
                    let secret = plane.client_secret(&account)?.unwrap_or_default();
                    let v = oidc::finish(
                        &self.ctx.sso,
                        egress,
                        &provider,
                        &flow,
                        request.code.trim(),
                        &secret,
                        now,
                    )
                    .await
                    .map_err(refuse)?;
                    (
                        v.issuer,
                        v.subject,
                        v.user_name,
                        v.display_name,
                        v.email,
                        v.email_verified,
                        v.stable_ids,
                    )
                }
                (SsoProtocol::Saml, true) => {
                    let v = saml::finish(
                        &self.ctx.sso,
                        &provider,
                        &flow,
                        request.saml_response.trim(),
                        now,
                    )
                    .map_err(refuse)?;
                    // SAML asserts no e-mail verification; the stable id is the
                    // NameID (or the mapped attribute for a transient one).
                    let ids = vec![v.subject.clone()];
                    (
                        v.issuer,
                        v.subject,
                        v.user_name,
                        v.display_name,
                        v.email,
                        false,
                        ids,
                    )
                }
                _ => {
                    return Err(refuse(
                        nornir_identity_sso::Refusal::ProviderChanged.message(),
                    ))
                }
            };
        let user_name = normalize_user_name(&user_name)
            .ok_or_else(|| refuse(nornir_identity_sso::Refusal::NamedNobody.message()))?;
        let room = self.room(&account)?;
        let outcome = plane
            .login(SsoLoginAsk {
                account: account.clone(),
                issuer,
                subject,
                user_name: user_name.clone(),
                display_name,
                email,
                email_verified,
                idp_ids,
                room,
                // The session is the identity core's (below), never a key.
                session: None,
                now_unix_ms: now,
            })
            .map_err(|err| match err {
                crate::seam::ControlError::FailedPrecondition(m) => {
                    self.audit(METHOD, "", &account, false, "sso.login_refused", &m);
                    Status::failed_precondition(m)
                }
                other => refuse(other.to_string()),
            })?;
        let principal_id = outcome.principal.id.clone();
        let mut answer = FinishResponse {
            principal: Some(outcome.principal.clone()),
            account: account.clone(),
            created: outcome.created,
            ..FinishResponse::default()
        };
        if provider.require_passkey {
            let passkeys = plane.passkeys_of(&principal_id)?;
            let register = passkeys.is_empty();
            let ticket = crate::webauthn::b64url(&crate::webauthn::random_bytes(32));
            self.ctx
                .sso
                .park_second(
                    hash(&ticket),
                    Second {
                        account: account.clone(),
                        principal_id: principal_id.clone(),
                        register,
                        // The shared ticket keeps a session-key slot (edda's
                        // `Second`); Gunnar's second factor mints a core session
                        // instead, so the slot stays empty.
                        session_openssh: String::new(),
                        session_expires_ms: 0,
                        expires_ms: now + SECOND_TTL_MS,
                    },
                    now,
                )
                .map_err(Status::resource_exhausted)?;
            if register {
                // The person's first passkey: the core's link onto them, as
                // short-lived as the ticket.
                let link = identity
                    .enrolment(
                        &principal_id,
                        &format!("sso:{account}"),
                        Some(SECOND_TTL_MS / 1000),
                    )
                    .map_err(crate::identity::status_of)?;
                answer.enrolment = link.secret;
            }
            answer.second_factor = if register {
                SecondFactorNeed::PasskeyRegistration
            } else {
                SecondFactorNeed::Passkey
            } as i32;
            answer.pending = ticket;
            answer.credential_ids = passkeys;
        } else {
            // **The identity core's session for whom the IdP vouched**: the
            // same opaque session a passkey login mints.
            let session = crate::identity::vouched_session(&identity, &principal_id, false)
                .map_err(crate::identity::status_of)?;
            // Company sign-on vouched: the session acts under `require_sso`.
            identity
                .host()
                .gunnar_store()
                .admit_sso_session(&session.token)
                .map_err(|e| Status::unavailable(e.0))?;
            // ...and may mint the employee's own credential (A34-24): the same persisted
            // admission says so (RA5-38).
            answer.session = session.token;
        }
        self.audit(
            METHOD,
            &principal_id,
            &account,
            true,
            "sso.login",
            &format!(
                "protocol={} created={} claimed={}{} second_factor={}",
                if flow.saml { "saml" } else { "oidc" },
                outcome.created,
                outcome.claimed,
                if outcome.claimed_by.is_empty() {
                    String::new()
                } else {
                    format!(" claimed_by={}", outcome.claimed_by)
                },
                provider.require_passkey
            ),
        );
        Ok(Response::new(answer))
    }

    /// **The passkey after the IdP** — the relay's.
    async fn second_factor(
        &self,
        request: Request<SecondFactorRequest>,
    ) -> Result<Response<SecondFactorResponse>, Status> {
        const METHOD: &str = "Sso.SecondFactor";
        self.relay(&request, METHOD)?;
        let request = request.into_inner();
        let now = now_ms();
        let second = self
            .ctx
            .sso
            .take_second(&hash(request.pending.trim()), now)
            .ok_or_else(|| {
                Status::permission_denied(nornir_identity_sso::Refusal::Expired.message())
            })?;
        let refuse = |why: String| {
            // By code (A34-46): the console maps it to its own words.
            let why = match nornir_identity_sso::code_of(&why) {
                Some(_) => why,
                None => nornir_identity_sso::Refusal::SecondFactor.with(&why),
            };
            self.audit(
                METHOD,
                &second.principal_id,
                &second.account,
                false,
                "sso.second_factor_refused",
                &why,
            );
            Status::permission_denied(format!("{METHOD} refused: {why}"))
        };
        // **The passkey was the identity core's** (a login, or the first
        // passkey's redemption): its session must be the person the IdP named.
        let identity = self.ctx.identity.clone().ok_or_else(|| {
            Status::unavailable("this server serves no identity core, so it signs nobody in")
        })?;
        let view = identity
            .session(request.session.trim())
            .map_err(|refused| {
                refuse(format!(
                    "the passkey's session is no session here ({})",
                    refused.code
                ))
            })?;
        if view.user_id != second.principal_id {
            return Err(refuse(
                "this passkey is not the signed-in person's".to_owned(),
            ));
        }
        // After the IdP, the passkey's session is admitted (`require_sso`).
        identity
            .host()
            .gunnar_store()
            .admit_sso_session(request.session.trim())
            .map_err(|e| Status::unavailable(e.0))?;
        let principal = self
            .ctx
            .control
            .principal(&second.principal_id)?
            .ok_or_else(|| Status::not_found(format!("no principal {}", second.principal_id)))?;
        self.audit(
            METHOD,
            &second.principal_id,
            &second.account,
            true,
            "sso.second_factor",
            if second.register {
                "registered the first passkey"
            } else {
                "passkey verified"
            },
        );
        Ok(Response::new(SecondFactorResponse {
            principal: Some(principal),
            user_verified: view.stepped_up,
        }))
    }

    /// **Prove a domain by DNS** (A34-5) — the account admin's, with a fresh touch:
    /// the TXT record is read through the operator-switched egress from the
    /// operator's resolver; only then does the domain lead sign-ins here.
    async fn verify_domain(
        &self,
        request: Request<VerifyDomainRequest>,
    ) -> Result<Response<VerifyDomainResponse>, Status> {
        const METHOD: &str = "Sso.VerifyDomain";
        let (caller, account) = self.admin_stepped_up(&request, |r| r.account.as_str(), METHOD)?;
        let raw = request.get_ref().domain.trim().to_owned();
        let domain = normalize_domain(&raw)
            .ok_or_else(|| Status::invalid_argument(format!("{raw:?} is not an email domain")))?;
        let plane = self.plane()?;
        let state = Arc::clone(&self.ctx.sso);
        let (who, what) = (account.clone(), domain.clone());
        // **No default public resolver** (RA5-24): the operator names the resolver
        // (`sso_dns_resolver`) or no proof is read; outbound needs explicit config (owner
        // rule 2026-10-25). Since nornir-identity-sso 0.1.2 edda's state keeps a blank
        // resolver blank (no dns.google default), so blank is the one "not fed".
        let resolver = state.dns_resolver();
        let resolver_named = !resolver.trim().is_empty();
        let read = match resolver_named {
            false => Err(crate::sso::Refusal::DomainResolver.with(NO_RESOLVER)),
            true => tokio::task::spawn_blocking(move || {
                crate::sso::domains::verify(&state, &who, &what)
            })
            .await
            .map_err(|e| Status::internal(format!("the DNS proof was not read: {e}")))?,
        };
        let proven = read.and_then(|()| {
            plane
                .verify_domain(&account, &domain)
                .map_err(|e| e.to_string())
        });
        match proven {
            Ok(saved) => {
                self.audit(
                    METHOD,
                    &caller.principal_id,
                    &account,
                    true,
                    "sso.domain_verified",
                    &format!("domain={domain}"),
                );
                Ok(Response::new(VerifyDomainResponse {
                    view: Some(self.view(saved)),
                }))
            }
            Err(why) => {
                self.audit(
                    METHOD,
                    &caller.principal_id,
                    &account,
                    false,
                    "sso.domain_refused",
                    &format!("domain={domain} {why}"),
                );
                Err(Status::failed_precondition(why))
            }
        }
    }

    /// **Open a rebind** (A34-11, an IdP migration) — the account admin's, with a
    /// fresh touch, audited.
    async fn rebind_users(
        &self,
        request: Request<RebindUsersRequest>,
    ) -> Result<Response<RebindUsersResponse>, Status> {
        const METHOD: &str = "Sso.RebindUsers";
        let (caller, account) = self.admin_stepped_up(&request, |r| r.account.as_str(), METHOD)?;
        let request = request.into_inner();
        let ids: Vec<String> = request
            .principal_ids
            .iter()
            .map(|p| p.trim().to_owned())
            .filter(|p| !p.is_empty())
            .collect();
        let rows = self
            .plane()?
            .rebind_users(&account, &ids, request.external_id.trim())?;
        self.audit(
            METHOD,
            &caller.principal_id,
            &account,
            true,
            "sso.rebind",
            &format!(
                "employees={} external_id={}",
                rows.len(),
                !request.external_id.trim().is_empty()
            ),
        );
        Ok(Response::new(RebindUsersResponse {
            users: rows.into_iter().map(Self::directory_user).collect(),
        }))
    }

    /// **One SCIM request** — relayed; the bearer decides the account.
    async fn scim(&self, request: Request<ScimRequest>) -> Result<Response<ScimResponse>, Status> {
        const METHOD: &str = "Sso.Scim";
        self.relay(&request, METHOD)?;
        let request = request.into_inner();
        let plane = self.plane()?;
        let now = now_ms();
        let respond = |answer: scim::Answer, ended: Vec<String>| {
            let body = if answer.body.is_null() {
                Vec::new()
            } else {
                serde_json::to_vec(&answer.body).unwrap_or_default()
            };
            Response::new(ScimResponse {
                status: u32::from(answer.status),
                body,
                content_type: scim::CONTENT_TYPE.to_owned(),
                location: answer.location,
                ended_sessions: ended,
            })
        };
        let bearer = request.bearer.trim();
        let token_hash = hash(bearer);
        let found = if bearer.is_empty() || bearer.len() > 512 {
            None
        } else {
            plane.scim_account(&token_hash)?
        };
        // A34-27: an expired bearer is refused as an unknown one is, with its
        // own sentence; every refusal is counted per client, so a flood of
        // them neither fills the audit log nor goes on answered at full speed.
        let refused = match &found {
            None => Some(scim::error_answer(
                401,
                None,
                "the bearer is unknown or revoked",
            )),
            Some((_, b)) => b.check(now).err(),
        };
        if let Some(answer) = refused {
            let client = request.client.trim();
            let detail = answer.body["detail"]
                .as_str()
                .unwrap_or_default()
                .to_owned();
            match scim::REFUSALS.refused(client, now) {
                scim::Refusal::Audit => self.audit(
                    METHOD,
                    "",
                    found.as_ref().map(|(a, _)| a.as_str()).unwrap_or(""),
                    false,
                    "sso.scim_refused",
                    &format!("{detail} (client {})", scim::bearer::client_key(client)),
                ),
                scim::Refusal::Quiet => {}
                scim::Refusal::Throttle => {
                    return Ok(respond(
                        scim::error_answer(
                            429,
                            None,
                            "too many refused requests from this client this minute",
                        ),
                        Vec::new(),
                    ))
                }
            }
            return Ok(respond(answer, Vec::new()));
        }
        let Some((account, bearer_rules)) = found else {
            unreachable!("a missing bearer was refused above");
        };
        if !self
            .ctx
            .sso
            .allow(&format!("scim:{token_hash}"), SCIM_PER_MINUTE, now)
        {
            return Ok(respond(
                scim::error_answer(429, None, "too many requests this minute"),
                Vec::new(),
            ));
        }
        let room = self.room(&account)?;
        let actor = format!("scim:{account}");
        let store = scim::PlaneDirectory {
            plane,
            account: &account,
            room,
            actor: &actor,
            now_unix_ms: now,
        };
        let call = scim::Call {
            method: request.method.trim(),
            path: request.path.trim(),
            query: request.query.trim(),
            body: &request.body,
            base_url: request.base_url.trim(),
            read_only: bearer_rules.scope == scim::Scope::Read,
        };
        let (answer, effect) = scim::handle(&store, &call);
        // A user deactivated or deleted had its web sessions revoked with it:
        // named in the answer, so the console signs them out too.
        let ended: Vec<String> = effect
            .as_ref()
            .and_then(scim::Effect::ended_session)
            .map(|p| vec![p.to_owned()])
            .unwrap_or_default();
        // ...and their identity-core sessions end here (IDENTITY-HOST): a
        // reactivation later does not bring the old ones back.
        if let Some(identity) = &self.ctx.identity {
            for principal in &ended {
                if let Err(refused) = identity.end_sessions(principal, &format!("scim:{account}")) {
                    tracing::warn!(target: AUDIT_TARGET, event = "sso.scim_sessions_not_ended", principal = %principal, reason = %refused, "a deactivated user's sessions could not be ended; the directory still refuses them");
                }
            }
        }
        if let Some(effect) = effect {
            self.audit(
                METHOD,
                &actor,
                &account,
                true,
                "sso.scim",
                &format!("{} {}", effect.what, effect.principal),
            );
        } else if answer.status >= 400 {
            tracing::info!(target: AUDIT_TARGET, event = "sso.scim_answer", account = %account, status = answer.status, method = %call.method, path = %call.path, "a SCIM request was answered with an error");
        }
        Ok(respond(answer, ended))
    }
}

/// An import job as `Sso.ImportUsers`/`Sso.ImportStatus` answer it.
fn import_answer(job: scim::ImportJob, dry_run: bool) -> ImportUsersResponse {
    let o = job.outcome;
    ImportUsersResponse {
        created: o.created,
        updated: o.updated,
        deactivated: o.deactivated,
        reactivated: o.reactivated,
        unchanged: o.unchanged,
        errors: o.errors,
        dry_run,
        job_id: job.job_id,
        state: job.state.to_owned(),
        error: job.error,
        done_rows: job.done_rows,
        total_rows: job.total_rows,
        ended_sessions: o.ended_sessions,
    }
}

/// Wire an egress into the context's SSO state (`gunnar-server` does).
pub fn with_egress(ctx: &crate::service::ServiceContext, egress: Arc<dyn crate::sso::Egress>) {
    ctx.sso.set_egress(egress);
}