Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Domain ports for upstream OAuth providers.
use std::{future::Future, pin::Pin, time::Duration};
use super::models::{
EmailCodeRequest, RefreshToken, RefreshTokenBinding, RegisteredClient, UpstreamLogin,
UpstreamTokens,
};
/// Boxed future returning a token grant from the upstream provider.
pub type UpstreamTokensFuture<'a> =
Pin<Box<dyn Future<Output = Result<UpstreamTokens, UpstreamGrantError>> + Send + 'a>>;
/// Why the upstream provider issued no tokens for a grant. Carries no
/// credential, so it is safe to log.
#[derive(Debug, thiserror::Error)]
pub enum UpstreamGrantError {
/// The provider refused the code or refresh token itself as invalid,
/// expired, or revoked. Only the user authorizing again fixes it.
#[error("upstream refused the grant: {detail}")]
InvalidGrant {
/// The provider's reason, for logs.
detail: String,
},
/// The provider was unreachable or throttling requests; retrying later
/// can succeed.
#[error("upstream is unavailable")]
Unavailable {
/// How long the provider asked callers to wait, when it said.
retry_after: Option<Duration>,
},
/// Anything else: a request or client credential the provider rejected,
/// which is ours to fix, or an answer we could not use.
#[error("upstream grant request failed: {0:#}")]
Failed(anyhow::Error),
}
/// Boxed future returning nothing on success.
pub type StoreWriteFuture<'a> = Pin<Box<dyn Future<Output = anyhow::Result<()>> + Send + 'a>>;
/// Boxed future returning a registered client, if one exists.
pub type RegisteredClientFuture<'a> =
Pin<Box<dyn Future<Output = anyhow::Result<Option<RegisteredClient>>> + Send + 'a>>;
/// Boxed future returning a refresh token binding, if one exists.
pub type RefreshTokenBindingFuture<'a> =
Pin<Box<dyn Future<Output = anyhow::Result<Option<RefreshTokenBinding>>> + Send + 'a>>;
/// Boxed future returning whether a grant has been revoked.
pub type GrantRevokedFuture<'a> = Pin<Box<dyn Future<Output = anyhow::Result<bool>> + Send + 'a>>;
/// Boxed future returning nothing once the upstream provider has acted.
pub type UpstreamRevocationFuture<'a> =
Pin<Box<dyn Future<Output = anyhow::Result<()>> + Send + 'a>>;
/// Store of clients created through dynamic client registration.
///
/// Registrations outlive a single handshake: a client registers once and then
/// authorizes repeatedly, so this is separate from the in-flight handshake
/// state and each entry must survive well beyond an authorization code.
pub trait ClientRegistrationStore: Send + Sync {
/// Persists a newly registered client.
fn insert_client<'a>(&'a self, client: &'a RegisteredClient) -> StoreWriteFuture<'a>;
/// Loads a registered client by id, returning `None` when the id is
/// unknown or its registration has lapsed.
///
/// Implementations may treat a successful lookup as use of the
/// registration and extend its lifetime accordingly.
fn find_client<'a>(&'a self, client_id: &'a str) -> RegisteredClientFuture<'a>;
}
/// Store recording which client and grant each outstanding refresh token was
/// issued to, and which grants have been revoked.
///
/// Refresh tokens are keyed by digest rather than by their own value so the
/// store never holds a usable credential.
pub trait RefreshTokenBindingStore: Send + Sync {
/// Binds a refresh token digest to the client and grant it belongs to,
/// replacing any existing binding for that digest.
fn bind<'a>(
&'a self,
refresh_token_digest: &'a str,
binding: &'a RefreshTokenBinding,
) -> StoreWriteFuture<'a>;
/// Returns the binding for a refresh token digest, if any.
fn binding<'a>(&'a self, refresh_token_digest: &'a str) -> RefreshTokenBindingFuture<'a>;
/// Drops the binding for a refresh token digest.
fn unbind<'a>(&'a self, refresh_token_digest: &'a str) -> StoreWriteFuture<'a>;
/// Records that a grant is revoked, so no refresh token in its family is
/// honored again. Must outlive every binding that names the grant.
fn revoke_grant<'a>(&'a self, grant_id: &'a str) -> StoreWriteFuture<'a>;
/// Returns whether a grant has been revoked.
fn is_grant_revoked<'a>(&'a self, grant_id: &'a str) -> GrantRevokedFuture<'a>;
}
/// Upstream OAuth provider used by the broker.
pub trait OAuthProvider: Send + Sync {
/// Builds the upstream authorize URL for a broker session.
fn construct_authorize_url(
&self,
state: &str,
login: UpstreamLogin<'_>,
) -> anyhow::Result<String>;
/// Exchanges an upstream authorization code for tokens.
fn exchange_authorization_code<'a>(&'a self, code: &'a str) -> UpstreamTokensFuture<'a>;
/// Refreshes an upstream access token using the refresh token grant.
fn refresh_access_token<'a>(
&'a self,
refresh_token: &'a RefreshToken,
) -> UpstreamTokensFuture<'a>;
/// Revokes an upstream refresh token. Succeeds when the provider no longer
/// knows the token, so a revocation can be retried.
fn revoke_refresh_token<'a>(
&'a self,
refresh_token: &'a RefreshToken,
) -> UpstreamRevocationFuture<'a>;
}
/// Boxed future returning the upstream's answer to an emailed code request.
pub type EmailCodeRequestFuture<'a> =
Pin<Box<dyn Future<Output = Result<EmailCodeRequest, EmailCodeError>> + Send + 'a>>;
/// Boxed future returning the tokens an emailed code redeems for.
pub type EmailCodeTokensFuture<'a> =
Pin<Box<dyn Future<Output = Result<UpstreamTokens, EmailCodeError>> + Send + 'a>>;
/// Why the upstream refused or failed an emailed code step.
#[derive(Debug, thiserror::Error)]
pub enum EmailCodeError {
/// The address is malformed.
#[error("invalid email address")]
InvalidEmail,
/// The address may not sign in.
#[error("email address may not sign in")]
NotAllowed,
/// The code is wrong or has expired.
#[error("invalid or expired code")]
InvalidCode,
/// Too many attempts for this address.
#[error("too many attempts")]
RateLimited,
/// The upstream could not be reached or answered unexpectedly.
#[error("email sign-in is unavailable")]
Unavailable(#[source] anyhow::Error),
}
/// Signs a user in with a one-time code sent to their email address.
///
/// Object-safe, like the other ports here, so the service holds it as a
/// trait object.
pub trait EmailCodeProvider: Send + Sync {
/// Emails a sign-in code, or reports the single sign-on the address needs.
fn request_code<'a>(&'a self, email: &'a str) -> EmailCodeRequestFuture<'a>;
/// Redeems an emailed code for tokens.
fn redeem_code<'a>(&'a self, email: &'a str, code: &'a str) -> EmailCodeTokensFuture<'a>;
}