Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
authentication_service
What it is
Account sign-in and identity feature: FusionAuth-backed login, session/JWT issuance, signup policy and allowlisting, OAuth/OAuth2 account linking (Google/Microsoft/GitHub), subscription checkout status, Cursor/Codex API key issuance, and account merge/link flows.
Start here
src/api.rs: route module list (login,oauth,oauth2,session,jwt,webhooks,signup_policy,codex,cursor_api_key,merge, ...).src/service/signup_policy/:SignupPolicybuilt at startup; enforced authoritatively by the FusionAuthuser.createwebhook (src/api/webhooks), not by the public precheck routes.src/config.rs+src/doppler_config.rs: env vars and the Doppler config validator binary (authentication_service_doppler_config).README.md: the Develop signup allowlist (bypass flag, rollout/rollback steps) and GTM invite links — read before touching signup policy.
Scope
- Owns: FusionAuth-backed login/session issuance, JWT minting, signup
allowlisting, OAuth/OAuth2 account linking, GTM invite links, the platform
status banner API (
crates/system_status), shared-mailbox relocation signup, Cursor/Codex API key endpoints, introductory trial eligibility and subscription checkout. - Not here: authorization/permission decisions on other entities →
crates/macro_authorization; metered AI credits →crates/ai_billing; team lifecycle and seats →crates/teams; a person's interface language (/user/language) →crates/user_language.
Recipes
- Add a route: domain crate (if any) →
src/api/<area>.rs→src/api.rs(router) →src/openapi.rs. - Change signup policy:
src/service/signup_policy/→src/config.rs→ the Develop allowlist rollout steps inREADME.md. - Add a config value:
src/config.rs→ Doppler projectauthentication-service→ verify withauthentication_service_doppler_config.
Checks
cargo test -p authentication_service(SQLX_OFFLINEunset).- Signup-policy changes specifically:
env -u DATABASE_URL cargo test -p authentication_service --bin authentication_service config::testandcargo run -p authentication_service --bin authentication_service_doppler_config.
Subscription checkout
src/service/subscription_checkout.rsowns introductory eligibility and checkout terms; its Stripe adapter reads every subscription status and page.GET /user/stripe/trial_eligibilityreads the authenticated customer's eligibility without creating checkout. Any prior subscription disqualifies the first-subscription trial, including canceled or incomplete subscriptions. The trial is Pro only. Max checkout is paid immediately, and a trialing Pro subscription that moves to Max ends the trial and starts a Max billing cycle now. A team's first Max seat does the same; seat changes on a subscription already trialing on Max keep its trial.- Nonterminal subscriptions (including past due, unpaid, paused, and incomplete)
require management; only canceled and incomplete-expired subscriptions allow
replacement. Eligibility includes
existingSubscriptionfor recovery UI. - Share checkout idempotency generations across Pro, Max, and trial terms. Reuse exact open offers; expire other open subscription sessions before replacement. Never advance a generation after an ambiguous provider failure. Complete the backend rollout before releasing clients that depend on these protections.
- Stripe can cache a create failure under its idempotency key. If no session
becomes visible, retries deliberately retain that key: rotating it could double
bill after an ambiguous create. Reconcile using the opaque customer, session,
and idempotency fields in
billing.checkouttraces and Stripe request logs; recover an existing subscription, reuse a confirmed matching checkout, or expire a confirmed obsolete open session before retrying. If there is no session to reconcile, escalate to Stripe/support and wait for Stripe's key retention to expire (at least 24 hours). Never invent a fresh key solely to bypass a failed response. - Keep eligibility reads and checkout validation on the same policy; the legacy
hasTrialedflag tracks trials only and cannot identify paid-only customers. - Deploy the eligibility endpoint before web clients that require it; otherwise the clients keep Pro checkout disabled until the lookup can succeed.
API-token exchange preserves verified incoming agent attribution; query/body inputs cannot select an agent, and ordinary user credentials remain unattributed.
Agent accounts
- An agent can do everything a person can, including inviting other agents. Do
not gate actions on
isAgent; it only changes signup and labeling. The one exception: only an agent can be an account manager, and an agent can't be managed (crates/account_manager). - Routes that mint credentials, link a sign-in, merge accounts, or delete the
account use
AccountHolderOrInternal, so an account manager's credential can't outlast its own revocation or lock the account's owner out. User."isAgent"is set in the FusionAuthuser.createwebhook, fromis_agenton/login/passwordless(carried as FusionAuth user data) or a pending agentteam_invite. Those agents skip the seeded content, Loops, and Meta. The webhook cannot see SSO state, sois_agenton/login/ssoflags a new account in/oauth/redirect(mark_agent), after that content has started.- The account exists before its email is verified, so an email signup's flag is
provisional: a code request or SSO sign-in without
is_agentreverts it (revert_unconfirmed_agent) until a key exists, setup is confirmed, or an agent invite is pending. POST /user/agent_setupjoins the inviting team and replaces theAgent signupAPI key. It is repeatable untiltutorialCompleteis true.POST /user/profile_picture/filereserves an SFS upload for API-key callers, sincestatic_file_servicecannot check keys. It caps a picture at 16 MB and a user at 20 uploads an hour, and signs the declared size into the upload URL so storage rejects any other size.PUTon that path takes the SFS id and accepts only the caller's PNG, JPEG, WebP, or GIF; it does not wait for the asynchronous upload event.
Gotchas
/mobile-welcome-emailcopies allowlisted ad parameters from the capture request onto the desktop signup link and always setssignup_flow=mobile_email. The web app keeps that set on the PostHog person when the account is identified. Do not takesignup_flowfrom the request.Answer third-party failures as 502/503, not 500: match
GithubError::Upstream(error)before a route's 500 catch-all, and answer aFusionAuthClientErrorwhoseupstream()is set with that error'sinto_response(). Document 502/503 withUpstreamErrorResponsein the route'sutoipa::path.Fail closed if team cleanup encounters an external chat: external chats require human ownership.
GitHub reconnect preserves the current link until OAuth completes. A different account returns 409; disconnect first to switch accounts. Missing grants report reauthentication; GitHub or FusionAuth outages answer 502/503, and other failures remain server errors. Deploy grant-refresh support before releasing clients that omit the pre-OAuth disconnect; older callbacks leave an existing grant unchanged.
/internal/google_access_tokenanswers 403 for every grant Google refuses for this user (InvalidGrant, andGrantBlockedfor policy codes such asaccess_not_configured); email and calendar callers then mark the link for reauthorization instead of retrying. Keep it 4xx: a 500 makes callers retry and trips the HTTP server-errors monitor. Macro's own OAuth client failing (invalid_client) stays a 500.FusionAuth reports a link owner that was deleted as
UserDoesNotExist. That user has no links or grants left, so answer the route's "not linked" outcome (404 no grant, 200 for an idempotent removal), not a 500.The signup allowlist has a temporary Develop-only bypass (
DEVELOPMENT_BYPASS_SIGNUP_ALLOWLIST) that overrides the allowlist even when present; seeREADME.mdbefore changing signup behavior.Denial responses and policy errors must never disclose configured allowlist addresses; never paste operational addresses into code, logs, or docs.
New Outlook connections need the deployment switch
OUTLOOK_CONNECTIONS_ENABLEDand the user's PostHog flagenable-outlook(src/domain/microsoft.rs), read withcrates/feature_flagsfor the Macro user id the web app identifies with./link/email/providersanswersoutlook: falseand/link/outlookanswers 404 for a new connection when either is off; reconnecting an inbox reads neither. A failed flag load closes new connections and logs one warning. WithoutPOSTHOG_API_KEY(local, tests) the switch alone decides. Each decision is theoutlook.flagspan field (on,off,error,unconfigured)./oauth2/{provider}/callbackverifies two signedstatekinds (src/account_link_state.rs): account links, which expire, and Microsoft admin-consent returns, which do not. A consent screen that ends without a code redirects a link flow to itsoriginal_urlwithemail_link_error(admin_consent_required,cancelled,failed); only theAADSTScode fromerror_descriptionis logged, never the description.A Google consent that asked for the mailbox but came back without
gmail.modify(the user left the Gmail boxes unchecked) is refused in the Google callback before any identity-provider link is written or replaced: the pending row is deleted, the partial grant is revoked at Google so the next consent screen lists every scope again, and the flow returns withemail_link_error=gmail_not_granted. Google's revocation drops the account's whole grant to Macro, so it is skipped when an inbox for that address still works (needs_reauthfalse); the refusal stands either way. Mirrors Outlook's required-scope check insrc/domain/microsoft.rs; Macro has no mailbox-less link for either provider./oauth/redirectwithout a code answers "Sign-in failed" and logsauth_handoff_failure=missing_codewith FusionAuth's error.invalid_origin("Invalid origin uri ") means the page that sent the browser to FusionAuth is missing frominfra/stacks/fusionauth-instance/origins.ts; these failures carry no user id.When the FusionAuth JWT populate lambda fails (its
fetchto/webhooks/user/jwttimes out after 2 s or gets a non-200), FusionAuth still issues the access token, just without the Macro claims./jwt/refreshrefreshes such tokens instead of rejecting them, and warns when FusionAuth returns one. It answers 429 for one issued under 30 s ago, so client retries (websocket reconnects refresh on every attempt) can't turn a lambda outage into a FusionAuth refresh per retry.
Related
Rules:
.agents/rules/config-and-service-urls.md,.agents/rules/rust/security.md· Skill:new-serviceThe HTTP boundary validates optional signed agent correlation without changing existing authorization.