io_imap/sasl/

auth_xoauth2.rs

//! IMAP SASL XOAUTH2 coroutine; supports both the non-IR and SASL-IR
//! (RFC 4959) flows.
//!
//! XOAUTH2 is Google's pre-standard OAuth 2.0 mechanism, also
//! accepted by Microsoft Exchange Online.
//!
//! The mechanism itself lives in io-sasl: this coroutine holds the IMAP
//! half of the exchange, the `AUTHENTICATE XOAUTH2` command, the
//! continuation requests, the tagged response and the post-auth
//! follow-ups, and asks [`SaslXoauth2`] what to put in each response.
//! The error dance is the mechanism's too: a challenge carrying the
//! rejection JSON is answered with the empty response Google documents,
//! and the JSON comes back out when the exchange is declared over.
//!
//! XOAUTH2: <https://developers.google.com/workspace/gmail/imap/xoauth2-protocol>
//! SASL-IR: <https://www.rfc-editor.org/rfc/rfc4959>
//!
//! # Example
//!
//! ```rust,no_run
//! use std::{
//!     io::{Read, Write},
//!     net::TcpStream,
//! };
//!
//! use io_imap::{
//!     codec::fragmentizer::Fragmentizer,
//!     coroutine::{ImapCoroutine, ImapCoroutineState, ImapYield},
//!     sasl::auth_xoauth2::{ImapAuthXoauth2, ImapAuthXoauth2Options},
//! };
//!
//! // Ready stream needed (TCP-connected, TLS-negotiated)
//! let mut stream = TcpStream::connect("localhost:143").unwrap();
//!
//! let mut fragmentizer = Fragmentizer::new(50 * 1024 * 1024);
//! let mut buf = [0u8; 4096];
//!
//! let opts = ImapAuthXoauth2Options::default();
//! let mut coroutine = ImapAuthXoauth2::new("alice@example.org", "oauth-token", opts);
//! let mut arg = None;
//!
//! let capability = loop {
//!     match coroutine.resume(&mut fragmentizer, arg.take()) {
//!         ImapCoroutineState::Yielded(ImapYield::WantsWrite(bytes)) => {
//!             stream.write_all(&bytes).unwrap();
//!         }
//!         ImapCoroutineState::Yielded(ImapYield::WantsRead) => {
//!             let n = stream.read(&mut buf).unwrap();
//!             arg = Some(&buf[..n]);
//!         }
//!         ImapCoroutineState::Complete(Ok(capability)) => break capability,
//!         ImapCoroutineState::Complete(Err(err)) => panic!("{err}"),
//!     }
//! };
//!
//! println!("{capability:?}");
//! ```

use core::{fmt, mem};

use alloc::{
    string::{String, ToString},
    vec::Vec,
};

use imap_codec::{
    AuthenticateDataCodec, CommandCodec,
    fragmentizer::Fragmentizer,
    imap_types::{
        auth::{AuthMechanism, AuthenticateData},
        command::{Command, CommandBody},
        core::{IString, NString, TagGenerator},
        response::{
            Capability, Code, CommandContinuationRequest, Data, StatusBody, StatusKind, Tagged,
        },
        secret::Secret,
    },
};
use io_sasl::{
    coroutine::*,
    xoauth2::{SaslXoauth2, SaslXoauth2Creds, SaslXoauth2Error},
};
use log::{debug, trace};
use secrecy::SecretString;
use thiserror::Error;

use crate::{coroutine::*, imap_try, rfc2971::id::*, rfc3501::capability::*, send::*};

/// Failure causes during the SASL XOAUTH2 flow.
#[derive(Clone, Debug, Error)]
pub enum ImapAuthXoauth2Error {
    /// The server rejected authentication with a tagged NO.
    #[error("IMAP AUTHENTICATE XOAUTH2 failed: NO {0}")]
    No(String),
    /// The server rejected authentication with a tagged NO after
    /// returning an error payload in a challenge.
    #[error("IMAP AUTHENTICATE XOAUTH2 failed: NO {info} ({err})")]
    NoWithError {
        /// The tagged NO response text.
        info: String,
        /// The error payload extracted from the challenge.
        err: String,
    },
    /// The server rejected the AUTHENTICATE command with a tagged BAD.
    #[error("IMAP AUTHENTICATE XOAUTH2 failed: BAD {0}")]
    Bad(String),
    /// The server closed the connection with an untagged BYE.
    #[error("IMAP AUTHENTICATE XOAUTH2 failed: BYE {0}")]
    Bye(String),
    /// The server never returned the final tagged response.
    #[error("IMAP AUTHENTICATE XOAUTH2 failed: server did not return a tagged response")]
    MissingTagged,
    /// The server never sent the expected continuation request.
    #[error(
        "IMAP AUTHENTICATE XOAUTH2 failed: server did not send the expected continuation request"
    )]
    ExpectedContinuationRequest,
    /// The server returned OK before the mechanism could complete.
    #[error(
        "IMAP AUTHENTICATE XOAUTH2 failed: server returned OK before the mechanism could complete"
    )]
    UnexpectedOk,
    /// The mechanism refused the exchange.
    ///
    /// A rejected token whose exchange the server ended with something
    /// other than a tagged NO lands here, carrying the JSON it sent,
    /// as does a challenge arriving out of order.
    #[error("IMAP AUTHENTICATE XOAUTH2 failed: {0}")]
    Mechanism(#[from] SaslXoauth2Error),
    /// The underlying send coroutine failed.
    #[error("IMAP AUTHENTICATE XOAUTH2 failed: {0}")]
    Send(#[from] ImapSendError),
    /// The follow-up CAPABILITY command failed.
    #[error(transparent)]
    Capability(#[from] ImapCapabilityGetError),
    /// The follow-up ID command failed.
    #[error(transparent)]
    ServerId(#[from] ImapServerIdError),
}

/// Options for [`ImapAuthXoauth2::new`].
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct ImapAuthXoauth2Options {
    /// `true` selects SASL-IR (RFC 4959, inline credentials);
    /// `false` selects the non-IR upload-after-challenge flow.
    pub initial_request: bool,
    /// Fetch CAPABILITY after authentication when the tagged response
    /// carries no capability data. Defaults to `false`.
    pub ensure_capabilities: bool,
    /// Chain an RFC 2971 ID round-trip right after authentication, as
    /// required by some providers.
    ///
    /// Defaults to `None` (no ID); an empty list sends ID NIL.
    pub auto_id: Option<Vec<(IString<'static>, NString<'static>)>>,
}

/// I/O-free SASL XOAUTH2 coroutine.
pub struct ImapAuthXoauth2 {
    state: State,
    mechanism: SaslXoauth2,
    observed: Vec<Capability<'static>>,
    opts: ImapAuthXoauth2Options,
}

impl ImapAuthXoauth2 {
    /// Builds a SASL XOAUTH2 coroutine authenticating `user` with the
    /// OAuth 2.0 bearer `token`.
    ///
    /// Depending on `opts.initial_request`, the credentials go inline
    /// with the AUTHENTICATE command (SASL-IR) or are uploaded after
    /// the server challenge.
    pub fn new(
        user: impl AsRef<str>,
        token: impl AsRef<str>,
        opts: ImapAuthXoauth2Options,
    ) -> Self {
        let mechanism = SaslXoauth2::new(SaslXoauth2Creds {
            username: user.as_ref().to_string(),
            token: SecretString::from(token.as_ref().to_string()),
        });

        Self {
            state: State::Start,
            mechanism,
            observed: Vec::new(),
            opts,
        }
    }

    // helper that tells if the coroutine needs to fetch capability or not (in
    // case found in data or untagged responses)
    fn wants_capability(
        &mut self,
        code: Option<Code<'static>>,
        data: Vec<Data<'static>>,
        untagged: Vec<StatusBody<'static>>,
    ) -> Option<State> {
        let mut new_capability = None;

        if let Some(Code::Capability(capability)) = code {
            new_capability.replace(capability);
        }

        for data in data {
            if let Data::Capability(capability) = data {
                new_capability.replace(capability);
            }
        }

        for StatusBody { code, .. } in untagged {
            if let Some(Code::Capability(capability)) = code {
                new_capability.replace(capability);
            }
        }

        if let Some(capability) = new_capability {
            self.observed = capability.into_iter().collect();
        }

        (self.opts.ensure_capabilities && self.observed.is_empty())
            .then(|| State::Capability(ImapCapabilityGet::new()))
    }

    // helper that tells if the coroutine needs to exchange ID with server
    fn wants_id(&mut self) -> Option<State> {
        let params = self.opts.auto_id.take()?;
        let wire = (!params.is_empty()).then_some(params);
        Some(State::Id(ImapServerId::new(ImapServerIdOptions {
            parameters: wire,
        })))
    }

    // helper that tells if the coroutine needs to send continuation auth data
    fn wants_continue(payload: Vec<u8>) -> State {
        let auth = AuthenticateData::r#continue(payload);
        let codec = AuthenticateDataCodec::new();
        State::Continue(ImapSend::new(codec, auth))
    }

    // helper that resumes SASL coroutine
    fn resume_sasl(&mut self, arg: SaslArg<'_>) -> Result<Option<Vec<u8>>, ImapAuthXoauth2Error> {
        match self.mechanism.resume(arg) {
            SaslCoroutineState::Yielded(SaslYield::WantsWrite(payload)) => Ok(Some(payload)),
            SaslCoroutineState::Yielded(SaslYield::WantsRead) => Ok(None),
            SaslCoroutineState::Complete(result) => result.map(|()| None).map_err(Into::into),
        }
    }

    // helper that turns a tagged NO into the reason the mechanism holds, when
    // it holds one: the JSON explaining a rejected token was sent in a
    // challenge, and the mechanism gives it up once the exchange is over
    fn no(&mut self, info: String) -> ImapAuthXoauth2Error {
        match self.mechanism.resume(SaslArg::Done) {
            SaslCoroutineState::Complete(Err(SaslXoauth2Error::Rejected(err))) => {
                ImapAuthXoauth2Error::NoWithError { info, err }
            }
            _ => ImapAuthXoauth2Error::No(info),
        }
    }
}

impl ImapCoroutine for ImapAuthXoauth2 {
    type Yield = ImapYield;
    type Return = Result<Vec<Capability<'static>>, ImapAuthXoauth2Error>;

    fn resume(
        &mut self,
        fragmentizer: &mut Fragmentizer,
        arg: Option<&[u8]>,
    ) -> ImapCoroutineState<Self::Yield, Self::Return> {
        loop {
            match &mut self.state {
                State::Start => {
                    let payload = match self.resume_sasl(SaslArg::None) {
                        Ok(payload) => payload,
                        Err(err) => return ImapCoroutineState::Complete(Err(err)),
                    };

                    // NOTE: the initial response travels inline only when the
                    // server was found to support RFC 4959, which is a decision
                    // taken before the exchange; otherwise it waits for the
                    // empty challenge.
                    let (initial_response, pending) = match payload {
                        Some(payload) if self.opts.initial_request => {
                            (Some(Secret::new(payload.into())), None)
                        }
                        payload => (None, payload),
                    };

                    let tag = TagGenerator::new().generate();
                    let body = CommandBody::Authenticate {
                        mechanism: AuthMechanism::XOAuth2,
                        initial_response,
                    };
                    let cmd = Command { tag, body };
                    trace!("send IMAP command {cmd:?}");

                    self.state = State::Send {
                        send: ImapSend::new(CommandCodec::new(), cmd),
                        pending,
                    };
                    debug!("{}", self.state);
                }
                State::Send { send, pending } => {
                    let out = imap_try!(send, fragmentizer, arg);

                    if let Some(bye) = out.bye {
                        let err = ImapAuthXoauth2Error::Bye(bye.text.to_string());
                        return ImapCoroutineState::Complete(Err(err));
                    }

                    if let Some(cr) = out.continuation_request {
                        // NOTE: with the credentials still held back this is
                        // the empty challenge inviting them; with them already
                        // inlined it carries the rejection JSON, which only
                        // the mechanism reads and answers.
                        let payload = match pending.take() {
                            Some(payload) => payload,
                            None => {
                                match self.resume_sasl(SaslArg::Input(&extract_challenge(cr))) {
                                    Ok(payload) => payload.unwrap_or_default(),
                                    Err(err) => return ImapCoroutineState::Complete(Err(err)),
                                }
                            }
                        };

                        self.state = Self::wants_continue(payload);
                        debug!("{}", self.state);
                        continue;
                    }

                    // NOTE: with the credentials inlined there is nothing left
                    // to send, so the tagged response ends the exchange here
                    // rather than after a continuation. Without them, a server
                    // finishing now never asked for what it is authenticating.
                    let inlined = pending.is_none();

                    let Some(Tagged { body, .. }) = out.tagged else {
                        let err = ImapAuthXoauth2Error::ExpectedContinuationRequest;
                        return ImapCoroutineState::Complete(Err(err));
                    };

                    let code = match body.kind {
                        StatusKind::Ok if inlined => body.code,
                        StatusKind::Ok => {
                            let err = ImapAuthXoauth2Error::UnexpectedOk;
                            return ImapCoroutineState::Complete(Err(err));
                        }
                        StatusKind::No => {
                            let err = self.no(body.text.to_string());
                            return ImapCoroutineState::Complete(Err(err));
                        }
                        StatusKind::Bad => {
                            let err = ImapAuthXoauth2Error::Bad(body.text.to_string());
                            return ImapCoroutineState::Complete(Err(err));
                        }
                    };

                    if let Err(err) = self.resume_sasl(SaslArg::Done) {
                        return ImapCoroutineState::Complete(Err(err));
                    }

                    if let Some(next) = self.wants_capability(code, out.data, out.untagged) {
                        self.state = next;
                        debug!("{}", self.state);
                        continue;
                    }

                    if let Some(next) = self.wants_id() {
                        self.state = next;
                        debug!("{}", self.state);
                        continue;
                    }

                    let capability = mem::take(&mut self.observed);
                    return ImapCoroutineState::Complete(Ok(capability));
                }
                State::Continue(send) => {
                    let out = imap_try!(send, fragmentizer, arg);

                    if let Some(bye) = out.bye {
                        let err = ImapAuthXoauth2Error::Bye(bye.text.to_string());
                        return ImapCoroutineState::Complete(Err(err));
                    }

                    if let Some(cr) = out.continuation_request {
                        let payload = match self.resume_sasl(SaslArg::Input(&extract_challenge(cr)))
                        {
                            Ok(payload) => payload.unwrap_or_default(),
                            Err(err) => return ImapCoroutineState::Complete(Err(err)),
                        };

                        self.state = Self::wants_continue(payload);
                        debug!("{}", self.state);
                        continue;
                    }

                    let Some(Tagged { body, .. }) = out.tagged else {
                        let err = ImapAuthXoauth2Error::MissingTagged;
                        return ImapCoroutineState::Complete(Err(err));
                    };

                    let code = match body.kind {
                        StatusKind::Ok => body.code,
                        StatusKind::No => {
                            let err = self.no(body.text.to_string());
                            return ImapCoroutineState::Complete(Err(err));
                        }
                        StatusKind::Bad => {
                            let err = ImapAuthXoauth2Error::Bad(body.text.to_string());
                            return ImapCoroutineState::Complete(Err(err));
                        }
                    };

                    // NOTE: the tagged OK ends the exchange, and the mechanism
                    // is told so rather than dropped: a token the server
                    // rejected mid-exchange is reported here, with the JSON
                    // that explained it, rather than read as a success.
                    if let Err(err) = self.resume_sasl(SaslArg::Done) {
                        return ImapCoroutineState::Complete(Err(err));
                    }

                    if let Some(next) = self.wants_capability(code, out.data, out.untagged) {
                        self.state = next;
                        debug!("{}", self.state);
                        continue;
                    }

                    if let Some(next) = self.wants_id() {
                        self.state = next;
                        debug!("{}", self.state);
                        continue;
                    }

                    let capability = mem::take(&mut self.observed);
                    return ImapCoroutineState::Complete(Ok(capability));
                }
                State::Capability(capability) => {
                    self.observed = imap_try!(capability, fragmentizer, arg);

                    if let Some(next) = self.wants_id() {
                        self.state = next;
                        debug!("{}", self.state);
                        continue;
                    }

                    let capability = mem::take(&mut self.observed);
                    return ImapCoroutineState::Complete(Ok(capability));
                }
                State::Id(id) => {
                    imap_try!(id, fragmentizer, arg);
                    let capability = mem::take(&mut self.observed);
                    return ImapCoroutineState::Complete(Ok(capability));
                }
            }
        }
    }
}

enum State {
    Start,
    Send {
        send: ImapSend<CommandCodec>,
        pending: Option<Vec<u8>>,
    },
    Continue(ImapSend<AuthenticateDataCodec>),
    Capability(ImapCapabilityGet),
    Id(ImapServerId),
}

impl fmt::Display for State {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Start => f.write_str("start mechanism"),
            Self::Send { pending, .. } if pending.is_some() => f.write_str("send auth"),
            Self::Send { .. } => f.write_str("send auth with ir"),
            Self::Continue(_) => f.write_str("send response"),
            Self::Capability(_) => f.write_str("fetch capabilities"),
            Self::Id(_) => f.write_str("send id"),
        }
    }
}

fn extract_challenge(cr: CommandContinuationRequest<'static>) -> Vec<u8> {
    match cr {
        CommandContinuationRequest::Basic(basic) => basic.text().to_string().into_bytes(),
        CommandContinuationRequest::Base64(data) => data.as_ref().to_vec(),
    }
}

#[cfg(test)]
mod tests {
    use core::str;

    use alloc::format;

    use crate::sasl::auth_xoauth2::*;

    #[test]
    fn ir_success_returns_ok() {
        let opts = ImapAuthXoauth2Options {
            initial_request: true,
            ..Default::default()
        };

        let mut auth = ImapAuthXoauth2::new("user@example.org", "oauth-token", opts);
        let mut frag = Fragmentizer::new(50 * 1024 * 1024);

        let bytes = expect_wants_write(&mut auth, &mut frag, None);
        let line = str::from_utf8(&bytes).expect("utf8 command");
        let tag = first_word(line);
        assert!(line.contains("AUTHENTICATE XOAUTH2 "));

        expect_wants_read(&mut auth, &mut frag);

        let reply = format!("{tag} OK AUTHENTICATE completed\r\n");
        expect_complete_ok(&mut auth, &mut frag, reply.as_bytes());
    }

    #[test]
    fn ir_invalid_token_returns_no_with_error() {
        let opts = ImapAuthXoauth2Options {
            initial_request: true,
            ..Default::default()
        };

        let mut auth = ImapAuthXoauth2::new("user@example.org", "expired-token", opts);
        let mut frag = Fragmentizer::new(50 * 1024 * 1024);

        let bytes = expect_wants_write(&mut auth, &mut frag, None);
        let tag = first_word(str::from_utf8(&bytes).expect("utf8 command"));

        expect_wants_read(&mut auth, &mut frag);

        let (err_json_b64, err_json) = fake_json_error();
        let challenge = format!("+ {err_json_b64}\r\n");
        let ack = expect_wants_write(&mut auth, &mut frag, Some(challenge.as_bytes()));
        assert_eq!(b"\r\n", &*ack);

        expect_wants_read(&mut auth, &mut frag);

        let reply = format!("{tag} NO SASL authentication failed\r\n");
        let err = expect_complete_err(&mut auth, &mut frag, reply.as_bytes());
        let ImapAuthXoauth2Error::NoWithError { info, err } = err else {
            panic!("expected ImapAuthXoauth2Error::NoWithError, got {err:?}");
        };
        assert_eq!(info, "SASL authentication failed");
        assert_eq!(err, err_json);
    }

    #[test]
    fn ir_tagged_bad_returns_bad_error() {
        let opts = ImapAuthXoauth2Options {
            initial_request: true,
            ..Default::default()
        };

        let mut auth = ImapAuthXoauth2::new("user@example.org", "oauth-token", opts);
        let mut frag = Fragmentizer::new(50 * 1024 * 1024);

        let bytes = expect_wants_write(&mut auth, &mut frag, None);
        let tag = first_word(str::from_utf8(&bytes).expect("utf8 command"));

        expect_wants_read(&mut auth, &mut frag);

        let reply = format!("{tag} BAD AUTHENTICATE not enabled\r\n");
        let err = expect_complete_err(&mut auth, &mut frag, reply.as_bytes());
        let ImapAuthXoauth2Error::Bad(text) = err else {
            panic!("expected ImapAuthXoauth2Error::Bad, got {err:?}");
        };
        assert_eq!(text, "AUTHENTICATE not enabled");
    }

    #[test]
    fn ir_rejected_token_acknowledged_then_ok_returns_mechanism_error() {
        let opts = ImapAuthXoauth2Options {
            initial_request: true,
            ..Default::default()
        };

        let mut auth = ImapAuthXoauth2::new("user@example.org", "expired-token", opts);
        let mut frag = Fragmentizer::new(50 * 1024 * 1024);

        let bytes = expect_wants_write(&mut auth, &mut frag, None);
        let tag = first_word(str::from_utf8(&bytes).expect("utf8 command"));

        expect_wants_read(&mut auth, &mut frag);

        let (err_json_b64, err_json) = fake_json_error();
        let challenge = format!("+ {err_json_b64}\r\n");
        expect_wants_write(&mut auth, &mut frag, Some(challenge.as_bytes()));
        expect_wants_read(&mut auth, &mut frag);

        // NOTE: a server answering the acknowledgement with OK contradicts the
        // rejection it just sent. The mechanism read that JSON and keeps it,
        // so the failure is reported with the reason rather than as a success.
        let reply = format!("{tag} OK AUTHENTICATE completed\r\n");
        let err = expect_complete_err(&mut auth, &mut frag, reply.as_bytes());
        let ImapAuthXoauth2Error::Mechanism(SaslXoauth2Error::Rejected(json)) = err else {
            panic!("expected ImapAuthXoauth2Error::Mechanism, got {err:?}");
        };
        assert_eq!(json, err_json);
    }

    #[test]
    fn non_ir_success_returns_ok() {
        let opts = ImapAuthXoauth2Options::default();
        let mut auth = ImapAuthXoauth2::new("user@example.org", "oauth-token", opts);
        let mut frag = Fragmentizer::new(50 * 1024 * 1024);

        let bytes = expect_wants_write(&mut auth, &mut frag, None);
        let line = str::from_utf8(&bytes).expect("utf8 command");
        let tag = first_word(line);
        assert!(line.trim_end().ends_with("AUTHENTICATE XOAUTH2"));

        expect_wants_read(&mut auth, &mut frag);

        let creds = expect_wants_write(&mut auth, &mut frag, Some(b"+ \r\n"));
        assert!(creds.ends_with(b"\r\n"));

        expect_wants_read(&mut auth, &mut frag);

        let reply = format!("{tag} OK AUTHENTICATE completed\r\n");
        expect_complete_ok(&mut auth, &mut frag, reply.as_bytes());
    }

    #[test]
    fn non_ir_invalid_token_returns_no_with_error() {
        let opts = ImapAuthXoauth2Options::default();
        let mut auth = ImapAuthXoauth2::new("user@example.org", "expired-token", opts);
        let mut frag = Fragmentizer::new(50 * 1024 * 1024);

        let bytes = expect_wants_write(&mut auth, &mut frag, None);
        let tag = first_word(str::from_utf8(&bytes).expect("utf8 command"));

        expect_wants_read(&mut auth, &mut frag);
        expect_wants_write(&mut auth, &mut frag, Some(b"+ \r\n"));
        expect_wants_read(&mut auth, &mut frag);

        let (err_json_b64, err_json) = fake_json_error();
        let challenge = format!("+ {err_json_b64}\r\n");
        let ack = expect_wants_write(&mut auth, &mut frag, Some(challenge.as_bytes()));
        assert_eq!(b"\r\n", &*ack);

        expect_wants_read(&mut auth, &mut frag);

        let reply = format!("{tag} NO SASL authentication failed\r\n");
        let err = expect_complete_err(&mut auth, &mut frag, reply.as_bytes());
        let ImapAuthXoauth2Error::NoWithError { info, err } = err else {
            panic!("expected ImapAuthXoauth2Error::NoWithError, got {err:?}");
        };
        assert_eq!(info, "SASL authentication failed");
        assert_eq!(err, err_json);
    }

    fn expect_wants_write(
        cor: &mut ImapAuthXoauth2,
        frag: &mut Fragmentizer,
        arg: Option<&[u8]>,
    ) -> Vec<u8> {
        match cor.resume(frag, arg) {
            ImapCoroutineState::Yielded(ImapYield::WantsWrite(bytes)) => bytes,
            state => panic!("expected WantsWrite, got {state:?}"),
        }
    }

    fn expect_wants_read(cor: &mut ImapAuthXoauth2, frag: &mut Fragmentizer) {
        match cor.resume(frag, None) {
            ImapCoroutineState::Yielded(ImapYield::WantsRead) => {}
            state => panic!("expected WantsRead, got {state:?}"),
        }
    }

    fn expect_complete_ok(cor: &mut ImapAuthXoauth2, frag: &mut Fragmentizer, reply: &[u8]) {
        match cor.resume(frag, Some(reply)) {
            ImapCoroutineState::Complete(Ok(_)) => {}
            state => panic!("expected Complete(Ok), got {state:?}"),
        }
    }

    fn expect_complete_err(
        cor: &mut ImapAuthXoauth2,
        frag: &mut Fragmentizer,
        reply: &[u8],
    ) -> ImapAuthXoauth2Error {
        match cor.resume(frag, Some(reply)) {
            ImapCoroutineState::Complete(Err(err)) => err,
            state => panic!("expected Complete(Err), got {state:?}"),
        }
    }

    fn first_word(line: &str) -> &str {
        line.split_whitespace()
            .next()
            .expect("first whitespace-separated token")
    }

    fn fake_json_error() -> (&'static str, &'static str) {
        (
            "eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUiOiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==",
            "{\"status\":\"401\",\"schemes\":\"Bearer\",\"scope\":\"https://mail.google.com/\"}",
        )
    }
}