Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat: local setup for testing new user email flow (#5280)

gbirman3b77993de5ae
diff --git a/Cargo.lock b/Cargo.lock
index 4d91e2ef3b..267d784166 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -13095,6 +13095,7 @@ version = "0.1.0"
dependencies = [
"anyhow",
"aws-sdk-s3",
+ "base64 0.22.1",
"channels",
"chrono",
"clap",
@@ -13104,6 +13105,7 @@ dependencies = [
"entity_access_db_utils",
"fusionauth",
"futures",
+ "jsonwebtoken 10.3.0",
"lexical_client",
"macro_aws_config",
"macro_db_client",
diff --git a/crates/fusionauth/src/identity_provider/search.rs b/crates/fusionauth/src/identity_provider/search.rs
index 616f10f42c..25f3fed053 100644
--- a/crates/fusionauth/src/identity_provider/search.rs
+++ b/crates/fusionauth/src/identity_provider/search.rs
@@ -29,6 +29,8 @@ pub(crate) async fn get_idp_id_by_name(
base_url: &str,
name: &str,
) -> Result<String> {
+ // NOTE: this API matches ZERO identity providers when an
+ // X-FusionAuth-TenantId header is present.
let res = client
.client()
.get(format!(
diff --git a/crates/fusionauth/src/lib.rs b/crates/fusionauth/src/lib.rs
index a847952bc3..373de8d01a 100644
--- a/crates/fusionauth/src/lib.rs
+++ b/crates/fusionauth/src/lib.rs
@@ -29,25 +29,19 @@ use anyhow::Context;
use reqwest::Url;
-/// An HTTP client with default Authorization and optional tenant headers.
+/// An HTTP client with a default Authorization header.
#[derive(Clone, Debug)]
pub struct AuthedClient {
inner: reqwest::Client,
}
-/// Used to specify what tenant id we want to use
-const FUSIONAUTH_TENANT_ID_HEADER: &str = "X-FusionAuth-TenantId";
-
impl AuthedClient {
- /// Creates a new authenticated client with the given API key and tenant ID.
- pub fn new(url: &str, api_key: String, tenant_id: String) -> Self {
- Self::with_tenant_header(api_key, tenant_id, should_infer_local_tenant_header(url))
- }
-
- fn with_tenant_header(api_key: String, tenant_id: String, include_tenant: bool) -> Self {
- let auth_headers = auth_headers(api_key, tenant_id, include_tenant);
+ /// Creates a new authenticated client with the given API key.
+ pub fn new(api_key: String) -> Self {
+ let mut headers = reqwest::header::HeaderMap::new();
+ headers.insert(reqwest::header::AUTHORIZATION, api_key.parse().unwrap());
let client = reqwest::Client::builder()
- .default_headers(auth_headers)
+ .default_headers(headers)
.build()
.unwrap();
@@ -60,25 +54,6 @@ impl AuthedClient {
}
}
-fn auth_headers(
- api_key: String,
- tenant_id: String,
- include_tenant: bool,
-) -> reqwest::header::HeaderMap {
- let mut headers = reqwest::header::HeaderMap::new();
- headers.insert(reqwest::header::AUTHORIZATION, api_key.parse().unwrap());
-
- if include_tenant {
- tracing::trace!(
- "inserting {} header into fusionauth authed client",
- FUSIONAUTH_TENANT_ID_HEADER
- );
- headers.insert(FUSIONAUTH_TENANT_ID_HEADER, tenant_id.parse().unwrap());
- }
-
- headers
-}
-
/// An HTTP client without authentication headers.
#[derive(Clone, Debug, Default)]
pub struct UnauthedClient {
@@ -122,40 +97,7 @@ pub struct FusionAuthClient {
impl FusionAuthClient {
/// Creates a new FusionAuth client with the given configuration.
- #[expect(clippy::too_many_arguments, reason = "too annoying to fix")]
pub fn new(
- tenant_id: String,
- api_key: String,
- client_id: String,
- client_secret: String,
- fusion_auth_base_url: String,
- oauth_redirect_uri: String,
- google_client_id: String,
- google_client_secret: String,
- ) -> Self {
- Self::new_inner(
- tenant_id,
- api_key,
- client_id,
- client_secret,
- fusion_auth_base_url,
- oauth_redirect_uri,
- google_client_id,
- google_client_secret,
- false,
- )
- }
-
- /// Creates a client for a local FusionAuth instance.
- ///
- /// Local FusionAuth contains multiple tenants, so this always sends the
- /// tenant header instead of inferring locality from the host port.
- #[expect(
- clippy::too_many_arguments,
- reason = "matches the existing constructor"
- )]
- pub fn new_for_local_instance(
- tenant_id: String,
api_key: String,
client_id: String,
client_secret: String,
@@ -164,39 +106,7 @@ impl FusionAuthClient {
google_client_id: String,
google_client_secret: String,
) -> Self {
- Self::new_inner(
- tenant_id,
- api_key,
- client_id,
- client_secret,
- fusion_auth_base_url,
- oauth_redirect_uri,
- google_client_id,
- google_client_secret,
- true,
- )
- }
-
- #[expect(
- clippy::too_many_arguments,
- reason = "shared constructor implementation"
- )]
- fn new_inner(
- tenant_id: String,
- api_key: String,
- client_id: String,
- client_secret: String,
- fusion_auth_base_url: String,
- oauth_redirect_uri: String,
- google_client_id: String,
- google_client_secret: String,
- force_tenant_header: bool,
- ) -> Self {
- let auth_client = if force_tenant_header {
- AuthedClient::with_tenant_header(api_key, tenant_id, true)
- } else {
- AuthedClient::new(&fusion_auth_base_url, api_key, tenant_id)
- };
+ let auth_client = AuthedClient::new(api_key);
let unauth_client = UnauthedClient::new();
let fusion_auth_public_url = fusion_auth_base_url.clone();
@@ -264,13 +174,5 @@ impl FusionAuthClient {
}
}
-/// Preserves automatic tenant-header behavior for the default local endpoints.
-/// Named-instance clients opt into local tenant behavior explicitly instead of
-/// inferring service identity from a host port.
-#[tracing::instrument(level = tracing::Level::TRACE)]
-fn should_infer_local_tenant_header(url: &str) -> bool {
- url.starts_with("http://fusionauth:9011") || url.starts_with("http://localhost:9011")
-}
-
#[cfg(test)]
mod test;
diff --git a/crates/fusionauth/src/test.rs b/crates/fusionauth/src/test.rs
index 9104602aec..a9f3bce271 100644
--- a/crates/fusionauth/src/test.rs
+++ b/crates/fusionauth/src/test.rs
@@ -3,7 +3,6 @@ use super::*;
#[test]
fn oauth_authorize_url_uses_public_url() {
let client = FusionAuthClient::new(
- "tenant-id".into(),
"api-key".into(),
"client-id".into(),
"client-secret".into(),
@@ -21,24 +20,3 @@ fn oauth_authorize_url_uses_public_url() {
assert!(url.starts_with("http://localhost:28005/oauth2/authorize?"));
assert!(!url.contains("fusionauth:9011"));
}
-
-#[test]
-fn named_instance_ports_do_not_infer_the_tenant_header() {
- assert!(should_infer_local_tenant_header("http://fusionauth:9011"));
- assert!(should_infer_local_tenant_header("http://localhost:9011"));
-
- assert!(!should_infer_local_tenant_header("http://localhost:28005"));
- assert!(!should_infer_local_tenant_header("http://localhost:28006"));
- assert!(!should_infer_local_tenant_header("http://localhost:28008"));
- assert!(!should_infer_local_tenant_header("http://localhost:28009"));
- assert!(!should_infer_local_tenant_header("http://localhost:28010"));
-}
-
-#[test]
-fn tenant_header_is_explicitly_configurable() {
- let without_tenant = auth_headers("api-key".into(), "tenant-id".into(), false);
- assert!(!without_tenant.contains_key(FUSIONAUTH_TENANT_ID_HEADER));
-
- let with_tenant = auth_headers("api-key".into(), "tenant-id".into(), true);
- assert_eq!(with_tenant[FUSIONAUTH_TENANT_ID_HEADER], "tenant-id");
-}
diff --git a/docker/docker-compose-databases.yml b/docker/docker-compose-databases.yml
index 04ad42da50..c3c8b7cbc3 100644
--- a/docker/docker-compose-databases.yml
+++ b/docker/docker-compose-databases.yml
@@ -6,6 +6,10 @@ name: macro
services:
postgres:
image: pgvector/pgvector:pg16
+ # The default 100 max_connections is exhausted when every service's pool
+ # fills under load (e.g. a large email backfill): workers then die on
+ # "pool timed out" / "too many clients". Local-only headroom.
+ command: postgres -c max_connections=500
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user"]
interval: 2s
diff --git a/infra/stacks/fusionauth-instance/templates/populate_jwt_local.js b/infra/stacks/fusionauth-instance/templates/populate_jwt_local.js
new file mode 100644
index 0000000000..a50dc1a01d
--- /dev/null
+++ b/infra/stacks/fusionauth-instance/templates/populate_jwt_local.js
@@ -0,0 +1,19 @@
+/* LOCAL-ONLY variant of populate_jwt.js, used by the run_local kickstart
+ (tooling/xtask/crates/xtask_local). Production enriches the JWT by calling
+ authentication-service over HTTP, but Lambda HTTP Connect is a licensed
+ FusionAuth feature that silently fails without a Reactor license. Local runs
+ unlicensed, so derive the claims instead: every user gets `macro|<email>`
+ regardless of signup method (production's webhook path lands on the same
+ convention, MacroUserIdStr::try_from_email). root_macro_id and
+ macro_organization_id are never populated: org-scoped JWT flows need the
+ licensed lambda.
+
+ BLOCK comments only in this file: FusionAuth's KickstartRunner flattens the
+ lambda body to a single line, so a `//` comment swallows all the code after
+ it. The Pulumi/API deploy path preserves newlines; kickstart does not. */
+/* biome-ignore lint/correctness/noUnusedVariables: FusionAuth invokes this by name. */
+function populate(jwt, user, _registration) {
+ jwt.fusion_user_id = user.id;
+ jwt.email = user.email;
+ jwt.macro_user_id = 'macro|' + user.email;
+}
diff --git a/infra/stacks/fusionauth-instance/templates/reconcile_secondary_idp_link.js b/infra/stacks/fusionauth-instance/templates/reconcile_secondary_idp_link.js
index 5e1b2c3d40..e324258d9c 100644
--- a/infra/stacks/fusionauth-instance/templates/reconcile_secondary_idp_link.js
+++ b/infra/stacks/fusionauth-instance/templates/reconcile_secondary_idp_link.js
@@ -1,16 +1,22 @@
-// Aborts an OpenIDConnect login whose id_token email doesn't match the FA user's
-// email. Triggers on FA links created via /link/gmail — those links bind a Google
-// account to a primary macro user as a secondary inbox; signing in with that
-// Google account must not yield a session for the primary user.
-//
-// Fails closed: missing jwt.email or user.email is treated the same as a
-// mismatch. Google always returns email when the openid+email scopes are
-// granted, so legitimate primary sign-ins always satisfy the check.
-//
-// Also maps Google's profile claims onto the user. Assigning a reconcile lambda
-// replaces FusionAuth's default one, so without this the user is created with no
-// name and the user.create webhook has nothing to seed the macro profile with.
-// biome-ignore lint/correctness/noUnusedVariables: FusionAuth invokes this by name.
+/* Aborts an OpenIDConnect login whose id_token email doesn't match the FA
+ user's email. Triggers on FA links created via /link/gmail: those links bind
+ a Google account to a primary macro user as a secondary inbox; signing in
+ with that Google account must not yield a session for the primary user.
+
+ Fails closed: missing jwt.email or user.email is treated the same as a
+ mismatch. Google always returns email when the openid+email scopes are
+ granted, so legitimate primary sign-ins always satisfy the check.
+
+ Also maps Google's profile claims onto the user. Assigning a reconcile
+ lambda replaces FusionAuth's default one, so without this the user is
+ created with no name and the user.create webhook has nothing to seed the
+ macro profile with.
+
+ BLOCK comments only in this file: it is deployed both via Pulumi (dev/prod)
+ and via the local kickstart, and FusionAuth's KickstartRunner flattens the
+ lambda body to a single line, so a `//` comment swallows all the code after
+ it. */
+/* biome-ignore lint/correctness/noUnusedVariables: FusionAuth invokes this by name. */
function reconcile(user, registration, jwt, id_token, tokens) {
var jwtEmail =
jwt && typeof jwt.email === 'string' ? jwt.email.toLowerCase() : null;
@@ -23,7 +29,7 @@ function reconcile(user, registration, jwt, id_token, tokens) {
);
}
- // Claims live on the userinfo response; fall back to the id_token.
+ /* Claims live on the userinfo response; fall back to the id_token. */
function claim(name) {
var value = jwt && jwt[name];
if (typeof value !== 'string' || !value.trim()) {
@@ -32,8 +38,8 @@ function reconcile(user, registration, jwt, id_token, tokens) {
return typeof value === 'string' && value.trim() ? value.trim() : null;
}
- // Only fill what's missing — this runs on every login, and the user may have
- // since changed their name in Macro.
+ /* Only fill what's missing: this runs on every login, and the user may have
+ since changed their name in Macro. */
if (!user.firstName) {
user.firstName = claim('given_name');
}
diff --git a/services/authentication_service/src/config.rs b/services/authentication_service/src/config.rs
index f24c837f12..c88c992d64 100644
--- a/services/authentication_service/src/config.rs
+++ b/services/authentication_service/src/config.rs
@@ -16,7 +16,6 @@ pub static BASE_URL: LazyLock<String> = LazyLock::new(|| {
env_vars! {
pub struct BaseUrl;
- pub struct FusionAuthTenantId;
pub struct FusionAuthApiSecretKey;
pub struct FusionAuthClientId;
pub struct FusionAuthClientSecretKey;
@@ -64,8 +63,6 @@ pub struct Config {
pub database_url: DatabaseUrl,
/// The Redis URI for the Redis this application should use.
pub redis_uri: RedisUri,
- /// FusionAuth Tenant Id
- pub fusionauth_tenant_id: FusionAuthTenantId,
/// FusionAuth API key secret name
pub fusionauth_api_key_secret_key: FusionAuthApiSecretKey,
/// FusionAuth client id
diff --git a/services/authentication_service/src/main.rs b/services/authentication_service/src/main.rs
index 5cbab0b67e..235858929f 100644
--- a/services/authentication_service/src/main.rs
+++ b/services/authentication_service/src/main.rs
@@ -167,7 +167,6 @@ async fn main() -> anyhow::Result<()> {
.unwrap_or(config.fusionauth_base_url.as_ref())
.to_owned();
let auth_client = fusionauth::FusionAuthClient::new(
- config.fusionauth_tenant_id.to_string(),
fusionauth_api_key,
config.fusionauth_client_id.to_string().clone(),
fusionauth_client_secret,
diff --git a/services/mcp_service/src/config.rs b/services/mcp_service/src/config.rs
index c5c6f99506..a9089b457d 100644
--- a/services/mcp_service/src/config.rs
+++ b/services/mcp_service/src/config.rs
@@ -39,7 +39,6 @@ env_vars! {
/// FusionAuth client id.
pub struct FusionauthClientId;
/// FusionAuth tenant id.
- pub struct FusionauthTenantId;
/// Secrets Manager secret name for the FusionAuth API key.
pub struct FusionauthApiKeySecretKey;
/// Secrets Manager secret name for the FusionAuth client secret.
@@ -86,7 +85,6 @@ pub struct Config {
/// Browser-reachable FusionAuth URL. Falls back to the API base URL when unset.
pub fusionauth_public_url: FusionauthPublicUrl,
pub fusionauth_client_id: FusionauthClientId,
- pub fusionauth_tenant_id: FusionauthTenantId,
pub fusionauth_api_key_secret_key: FusionauthApiKeySecretKey,
pub fusionauth_client_secret_key: FusionauthClientSecretKey,
pub google_client_id: GoogleClientId,
diff --git a/services/mcp_service/src/context.rs b/services/mcp_service/src/context.rs
index 7a6c6a89ad..aef036ace6 100644
--- a/services/mcp_service/src/context.rs
+++ b/services/mcp_service/src/context.rs
@@ -416,7 +416,6 @@ async fn build_auth_proxy(
.unwrap_or(config.fusionauth_base_url.as_ref())
.to_owned();
let fusionauth_client = fusionauth::FusionAuthClient::new(
- config.fusionauth_tenant_id.as_ref().to_owned(),
fusionauth_api_key.as_ref().to_owned(),
config.fusionauth_client_id.as_ref().to_owned(),
fusionauth_client_secret.as_ref().to_owned(),
diff --git a/tooling/seed_cli/Cargo.toml b/tooling/seed_cli/Cargo.toml
index 1e9b0a78f4..8713d45d3b 100644
--- a/tooling/seed_cli/Cargo.toml
+++ b/tooling/seed_cli/Cargo.toml
@@ -7,6 +7,7 @@ version = "0.1.0"
[dependencies]
anyhow = { workspace = true }
aws-sdk-s3 = { workspace = true }
+base64 = { workspace = true }
channels = { path = "../../crates/channels", default-features = false, features = ["outbound"] }
chrono = { workspace = true }
clap = { workspace = true }
@@ -15,6 +16,7 @@ email_db_client = { path = "../../crates/email_db_client" }
entity_access = { path = "../../crates/entity_access", default-features = false, features = ["outbound"] }
entity_access_db_utils = { path = "../../crates/entity_access_db_utils" }
fusionauth = { path = "../../crates/fusionauth" }
+jsonwebtoken = { workspace = true }
futures = { workspace = true }
lexical_client = { path = "../../crates/lexical_client" }
macro_aws_config = { path = "../../crates/macro_aws_config", features = ["s3"] }
diff --git a/tooling/seed_cli/justfile b/tooling/seed_cli/justfile
index 0108a07812..9ee724444b 100644
--- a/tooling/seed_cli/justfile
+++ b/tooling/seed_cli/justfile
@@ -15,6 +15,20 @@ get_environment:
seed *ARGS:
cargo r "$@"
+# Seed/reset/status a REAL @macro-test.com Gmail test mailbox via the Gmail
+# API. Credentials come from AWS Secrets Manager, so an authenticated `aws` CLI is required.
+# just gmail seed --account [email protected] --count 10000
+# just gmail reset --account [email protected]
+# just gmail status --account [email protected]
+[positional-arguments]
+gmail *ARGS:
+ @GOOGLE_CLIENT_ID="${GOOGLE_CLIENT_ID:-$(aws secretsmanager get-secret-value --secret-id google-client-id-local --query SecretString --output text)}" \
+ GOOGLE_CLIENT_SECRET_KEY="${GOOGLE_CLIENT_SECRET_KEY:-$(aws secretsmanager get-secret-value --secret-id google-client-secret-local --query SecretString --output text)}" \
+ GMAIL_TEST_ACCOUNT_TOKENS="${GMAIL_TEST_ACCOUNT_TOKENS:-$(aws secretsmanager get-secret-value --secret-id gmail-test-account-tokens --query SecretString --output text)}" \
+ GMAIL_FORWARDER_SA_KEY="${GMAIL_FORWARDER_SA_KEY:-$(aws secretsmanager get-secret-value --secret-id gmail-local-watch-forwarder-sa --query SecretString --output text)}" \
+ SQLX_OFFLINE="true" \
+ cargo r -- gmail "$@"
+
# Reset and seed deterministic data for the local Playwright smoke suite.
local-e2e-smoke:
LOCAL_E2E_SEED="true" \
@@ -27,7 +41,6 @@ local-e2e-smoke:
ENVIRONMENT="local" \
FUSIONAUTH_BASE_URL="http://localhost:9011" \
FUSIONAUTH_API_KEY_SECRET_KEY="local" \
- FUSIONAUTH_TENANT_ID="local" \
FUSIONAUTH_CLIENT_ID="local" \
FUSIONAUTH_CLIENT_SECRET_KEY="local" \
FUSIONAUTH_OAUTH_REDIRECT_URI="http://localhost:8080/oauth/redirect" \
@@ -49,7 +62,6 @@ scenario *ARGS:
ENVIRONMENT="local" \
FUSIONAUTH_BASE_URL="${FUSIONAUTH_BASE_URL:-http://localhost:9011}" \
FUSIONAUTH_API_KEY_SECRET_KEY="${FUSIONAUTH_API_KEY_SECRET_KEY:-bf69486b-4733-4954-a44e-2e1b5f2c8a91}" \
- FUSIONAUTH_TENANT_ID="${FUSIONAUTH_TENANT_ID:-11111111-1111-4111-8111-111111111111}" \
FUSIONAUTH_CLIENT_ID="${FUSIONAUTH_CLIENT_ID:-22222222-2222-4222-8222-222222222222}" \
FUSIONAUTH_CLIENT_SECRET_KEY="${FUSIONAUTH_CLIENT_SECRET_KEY:-local}" \
FUSIONAUTH_OAUTH_REDIRECT_URI="http://localhost:8080/oauth/redirect" \
diff --git a/tooling/seed_cli/src/config.rs b/tooling/seed_cli/src/config.rs
index 2648750ece..950f492ee4 100644
--- a/tooling/seed_cli/src/config.rs
+++ b/tooling/seed_cli/src/config.rs
@@ -12,8 +12,6 @@ env_var! {
pub FusionauthBaseUrl,
/// fusionauth api key
pub FusionauthApiKeySecretKey,
- /// fusionauth tenant id
- pub FusionauthTenantId,
/// fusionauth client id
pub FusionauthClientId,
/// fusionauth client secret key
@@ -34,6 +32,15 @@ maybe_env_vars! {
pub struct InternalApiSecretKey;
/// frontend dev server port, for the per-persona URLs apply prints
pub struct FrontendPort;
+ /// Google OAuth client id for the gmail entity (local Internal client)
+ pub struct GoogleClientId;
+ /// Google OAuth client secret for the gmail entity (in local mode this
+ /// env var holds the secret value itself)
+ pub struct GoogleClientSecretKey;
+ /// JSON map of test-account email -> refresh token for the gmail entity
+ pub struct GmailTestAccountTokens;
+ /// GCP service-account key JSON for `gmail forward` (Pub/Sub subscriber)
+ pub struct GmailForwarderSaKey;
}
/// Clients for initializing native markdown document content.
diff --git a/tooling/seed_cli/src/entity/email/mod.rs b/tooling/seed_cli/src/entity/email/mod.rs
index fd8a7f2caf..8fce212e77 100644
--- a/tooling/seed_cli/src/entity/email/mod.rs
+++ b/tooling/seed_cli/src/entity/email/mod.rs
@@ -9,7 +9,7 @@
#[cfg(test)]
mod test;
-mod sample_bodies;
+pub(crate) mod sample_bodies;
use std::path::Path;
use std::sync::Arc;
@@ -162,7 +162,7 @@ pub struct SeedMessage {
}
/// Fake contacts used for generating seed data.
-const FAKE_CONTACTS: &[(&str, &str)] = &[
+pub(crate) const FAKE_CONTACTS: &[(&str, &str)] = &[
("[email protected]", "Alice Johnson"),
("[email protected]", "Bob Smith"),
("[email protected]", "Carol Williams"),
@@ -192,7 +192,7 @@ const SYSTEM_LABELS: &[(&str, &str)] = &[
];
/// Subject lines to randomly pick from.
-const SUBJECTS: &[&str] = &[
+pub(crate) const SUBJECTS: &[&str] = &[
"Meeting Follow-up",
"Project Update",
"Quick Question",
diff --git a/tooling/seed_cli/src/entity/gmail/mod.rs b/tooling/seed_cli/src/entity/gmail/mod.rs
new file mode 100644
index 0000000000..5b18ded58b
--- /dev/null
+++ b/tooling/seed_cli/src/entity/gmail/mod.rs
@@ -0,0 +1,917 @@
+//! Seed REAL Gmail test mailboxes (`@macro-test.com`) through the Gmail API.
+//!
+//! Unlike `entity::email` (which fabricates rows directly in the local
+//! database), this imports messages into an actual Workspace test account so
+//! the real connect → backfill → sync pipeline has something to pull
+//! (macro-2634). Deterministic: the same `--rng-seed` and `--count` produce
+//! the same mailbox shape.
+//!
+//! Auth: a stored refresh token per account (`GMAIL_TEST_ACCOUNT_TOKENS`, a
+//! JSON map of account email → refresh token) issued by the Internal OAuth
+//! client (`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET_KEY` — in local mode the
+//! latter holds the secret value itself). `just gmail …` in this crate's
+//! justfile pulls all three from AWS Secrets Manager.
+
+use std::collections::BTreeMap;
+use std::time::{Duration, Instant};
+
+use anyhow::{Context, bail};
+use base64::Engine;
+use base64::engine::general_purpose::{STANDARD, URL_SAFE, URL_SAFE_NO_PAD};
+use chrono::{DateTime, Utc};
+use clap::{Args, Subcommand};
+use rand::rngs::StdRng;
+use rand::{Rng, SeedableRng};
+
+#[cfg(test)]
+mod test;
+
+use crate::config::{
+ GmailForwarderSaKey, GmailTestAccountTokens, GoogleClientId, GoogleClientSecretKey,
+};
+use crate::entity::email::{FAKE_CONTACTS, SUBJECTS, sample_bodies};
+
+const GMAIL_BASE: &str = "https://gmail.googleapis.com/gmail/v1/users/me";
+const TOKEN_URL: &str = "https://oauth2.googleapis.com/token";
+/// Hard safety line: this tool only ever touches dedicated test accounts.
+const TEST_DOMAIN: &str = "@macro-test.com";
+
+/// Arguments for the `gmail` entity command.
+#[derive(Debug, Args)]
+pub struct GmailArgs {
+ /// The gmail action to perform
+ #[command(subcommand)]
+ pub command: GmailCommand,
+}
+
+/// Actions against a real test mailbox.
+#[derive(Debug, Subcommand)]
+pub enum GmailCommand {
+ /// Import deterministic fixture messages into a test mailbox
+ Seed(SeedArgs),
+ /// Delete every message in a test mailbox (including spam/trash)
+ Reset(AccountArg),
+ /// Print the mailbox's message/thread totals
+ Status(AccountArg),
+ /// Forward Gmail push notifications from the Pub/Sub subscription to a
+ /// local stack's webhook, so connected inboxes sync live (runs forever)
+ Forward(ForwardArgs),
+}
+
+/// Arguments for `gmail forward`.
+#[derive(Debug, Args)]
+pub struct ForwardArgs {
+ /// The local email-service webhook to deliver notifications to, through
+ /// the instance proxy (e.g. http://localhost:50009/email/gmail/webhook
+ /// for `--instance 2634`)
+ #[arg(long, default_value = "http://localhost:8090/email/gmail/webhook")]
+ target: String,
+ /// The Pub/Sub pull subscription attached to the Gmail watch topic
+ #[arg(
+ long,
+ default_value = "projects/macro-email-testing/subscriptions/gmail-local-watch-sub"
+ )]
+ subscription: String,
+ /// OIDC audience the webhook validates (`GmailClient` hardcodes this)
+ #[arg(long, default_value = "macro-gmail-webhook")]
+ webhook_audience: String,
+ /// Topic to attach the subscription to if it does not exist yet
+ #[arg(
+ long,
+ default_value = "projects/macro-email-testing/topics/gmail-local-watch"
+ )]
+ topic: String,
+}
+
+/// Arguments for `gmail seed`.
+#[derive(Debug, Args)]
+pub struct SeedArgs {
+ /// Test account to import into (must be @macro-test.com)
+ #[arg(long)]
+ account: String,
+ /// Total number of messages to import
+ #[arg(long, default_value_t = 10_000)]
+ count: usize,
+ /// RNG seed: same seed + count → same mailbox shape
+ #[arg(long, default_value_t = 42)]
+ rng_seed: u64,
+ /// Imports per second (import costs 25 quota units against a 250
+ /// units/sec/user cap, so keep this below 10)
+ #[arg(long, default_value_t = 6)]
+ rps: u64,
+ /// Skip the first N generated messages (resume an interrupted run — the
+ /// generation is deterministic, so the remainder picks up exactly where
+ /// the previous run stopped)
+ #[arg(long, default_value_t = 0)]
+ offset: usize,
+ /// Concurrent in-flight imports (paced by --rps regardless)
+ #[arg(long, default_value_t = 5)]
+ concurrency: usize,
+}
+
+/// Arguments naming just the target account.
+#[derive(Debug, Args)]
+pub struct AccountArg {
+ /// Test account (must be @macro-test.com)
+ #[arg(long)]
+ account: String,
+}
+
+impl GmailArgs {
+ /// Execute the gmail command. Deliberately does not take the
+ /// `SeedCliContext`: this talks only to Google, so it must work without
+ /// the local stack (DB) running.
+ pub async fn execute(self) -> anyhow::Result<()> {
+ match self.command {
+ GmailCommand::Seed(args) => seed(args).await,
+ GmailCommand::Reset(args) => reset(args).await,
+ GmailCommand::Status(args) => status(args).await,
+ GmailCommand::Forward(args) => forward(args).await,
+ }
+ }
+}
+
+fn http_client() -> anyhow::Result<reqwest::Client> {
+ reqwest::Client::builder()
+ .timeout(Duration::from_secs(120))
+ .build()
+ .context("building the HTTP client")
+}
+
+fn require_test_account(email: &str) -> anyhow::Result<()> {
+ if !email.ends_with(TEST_DOMAIN) {
+ bail!("refusing to touch {email}: only {TEST_DOMAIN} test accounts are allowed");
+ }
+ Ok(())
+}
+
+/// An authenticated Gmail API client for one test account, with retry,
+/// pacing-agnostic backoff, and automatic access-token refresh. Shareable
+/// across concurrent import tasks (`&self` everywhere; the token refresh is
+/// single-flight behind `refresh_gate`).
+struct GmailApi {
+ http: reqwest::Client,
+ access_token: tokio::sync::RwLock<String>,
+ refresh_gate: tokio::sync::Mutex<()>,
+ client_id: String,
+ client_secret: String,
+ refresh_token: String,
+}
+
+impl GmailApi {
+ async fn for_account(account: &str) -> anyhow::Result<Self> {
+ require_test_account(account)?;
+ let client_id = GoogleClientId::new()
+ .context(
+ "GOOGLE_CLIENT_ID is not set (use `just gmail …` to pull it from Secrets Manager)",
+ )?
+ .to_string();
+ let client_secret = GoogleClientSecretKey::new()
+ .context("GOOGLE_CLIENT_SECRET_KEY is not set (use `just gmail …`)")?
+ .to_string();
+ let tokens = GmailTestAccountTokens::new()
+ .context("GMAIL_TEST_ACCOUNT_TOKENS is not set (use `just gmail …`)")?
+ .to_string();
+ let tokens: BTreeMap<String, String> = serde_json::from_str(&tokens)
+ .context("GMAIL_TEST_ACCOUNT_TOKENS is not a JSON map of email → refresh token")?;
+ let refresh_token = tokens
+ .get(account)
+ .with_context(|| {
+ format!(
+ "no refresh token stored for {account}; known accounts: {:?}",
+ tokens.keys().collect::<Vec<_>>()
+ )
+ })?
+ .clone();
+
+ let api = GmailApi {
+ http: http_client()?,
+ access_token: tokio::sync::RwLock::new(String::new()),
+ refresh_gate: tokio::sync::Mutex::new(()),
+ client_id,
+ client_secret,
+ refresh_token,
+ };
+ api.refresh_access_token(String::new()).await?;
+ Ok(api)
+ }
+
+ /// Refresh the access token, single-flight: concurrent 401s all pass the
+ /// token they failed with, and whoever loses the race to the gate returns
+ /// immediately if the token has already been replaced.
+ async fn refresh_access_token(&self, failed_token: String) -> anyhow::Result<()> {
+ let _gate = self.refresh_gate.lock().await;
+ if *self.access_token.read().await != failed_token {
+ return Ok(());
+ }
+ let resp: serde_json::Value = self
+ .http
+ .post(TOKEN_URL)
+ .form(&[
+ ("client_id", self.client_id.as_str()),
+ ("client_secret", self.client_secret.as_str()),
+ ("refresh_token", self.refresh_token.as_str()),
+ ("grant_type", "refresh_token"),
+ ])
+ .send()
+ .await
+ .context("refresh-token request failed")?
+ .json()
+ .await
+ .context("refresh-token response was not JSON")?;
+ *self.access_token.write().await = resp["access_token"]
+ .as_str()
+ .with_context(|| format!("no access_token in refresh response: {resp}"))?
+ .to_string();
+ Ok(())
+ }
+
+ /// POST/GET with exponential backoff on 429/5xx and a one-shot token
+ /// refresh on 401. Returns the response body for 2xx.
+ async fn call(
+ &self,
+ method: reqwest::Method,
+ url: &str,
+ body: Option<&serde_json::Value>,
+ ) -> anyhow::Result<serde_json::Value> {
+ let mut refreshed = false;
+ for attempt in 0..7u32 {
+ let token = self.access_token.read().await.clone();
+ let mut req = self.http.request(method.clone(), url).bearer_auth(&token);
+ if let Some(body) = body {
+ req = req.json(body);
+ }
+ let resp = match req.send().await {
+ Ok(resp) => resp,
+ Err(e) if attempt < 6 => {
+ tracing::warn!(error=?e, attempt, "gmail request error, backing off");
+ tokio::time::sleep(Duration::from_secs(1 << attempt)).await;
+ continue;
+ }
+ Err(e) => return Err(e).context("gmail request failed after retries"),
+ };
+ let status = resp.status();
+ if status.is_success() {
+ if status == reqwest::StatusCode::NO_CONTENT {
+ return Ok(serde_json::Value::Null);
+ }
+ return resp.json().await.context("gmail response was not JSON");
+ }
+ if status == reqwest::StatusCode::UNAUTHORIZED && !refreshed {
+ refreshed = true;
+ self.refresh_access_token(token).await?;
+ continue;
+ }
+ // Gmail reports per-user quota exhaustion as 403 rateLimitExceeded
+ // (not 429); it is transient and must back off like a 429.
+ if status == reqwest::StatusCode::FORBIDDEN {
+ let text = resp.text().await.unwrap_or_default();
+ if text.contains("rateLimitExceeded") && attempt < 6 {
+ tracing::warn!(attempt, "gmail per-user quota exceeded, backing off");
+ tokio::time::sleep(Duration::from_secs(1 << attempt)).await;
+ continue;
+ }
+ bail!("gmail request to {url} failed: {status}: {text}");
+ }
+ if (status == reqwest::StatusCode::TOO_MANY_REQUESTS || status.is_server_error())
+ && attempt < 6
+ {
+ tracing::warn!(%status, attempt, "gmail request throttled, backing off");
+ tokio::time::sleep(Duration::from_secs(1 << attempt)).await;
+ continue;
+ }
+ let text = resp.text().await.unwrap_or_default();
+ bail!("gmail request to {url} failed: {status}: {text}");
+ }
+ bail!("gmail request to {url} failed: retries exhausted")
+ }
+}
+
+/// A leaky-bucket pacer: each caller takes the next start slot (spaced
+/// `1/rps` apart) and sleeps until it. Bounds the request START rate across
+/// all concurrent import tasks regardless of response latency.
+struct Pacer {
+ next_slot: tokio::sync::Mutex<tokio::time::Instant>,
+ step: Duration,
+}
+
+impl Pacer {
+ fn new(rps: u64) -> Self {
+ Pacer {
+ next_slot: tokio::sync::Mutex::new(tokio::time::Instant::now()),
+ step: Duration::from_millis(1000 / rps.max(1)),
+ }
+ }
+
+ async fn wait_turn(&self) {
+ let slot = {
+ let mut next = self.next_slot.lock().await;
+ let now = tokio::time::Instant::now();
+ let slot = (*next).max(now);
+ *next = slot + self.step;
+ slot
+ };
+ tokio::time::sleep_until(slot).await;
+ }
+}
+
+/// One planned RFC 2822 message.
+struct PlannedMessage {
+ message_id: String,
+ date: DateTime<Utc>,
+ from: (String, String),
+ to: (String, String),
+ subject: String,
+ references: Vec<String>,
+ labels: Vec<&'static str>,
+ body: String,
+}
+
+impl PlannedMessage {
+ fn to_rfc2822(&self) -> String {
+ let mut headers = vec![
+ format!("Message-ID: {}", self.message_id),
+ format!("Date: {}", self.date.to_rfc2822()),
+ format!("From: {} <{}>", self.from.1, self.from.0),
+ format!("To: {} <{}>", self.to.1, self.to.0),
+ format!("Subject: {}", self.subject),
+ ];
+ if let Some(parent) = self.references.last() {
+ headers.push(format!("In-Reply-To: {parent}"));
+ headers.push(format!("References: {}", self.references.join(" ")));
+ }
+ headers.push("MIME-Version: 1.0".to_string());
+ headers.push("Content-Type: text/plain; charset=\"UTF-8\"".to_string());
+ let body = self.body.replace('\n', "\r\n");
+ format!("{}\r\n\r\n{}", headers.join("\r\n"), body)
+ }
+}
+
+/// Deterministically generate the full mailbox plan. Thread-structured: ~30%
+/// of threads have 2–5 messages with alternating direction (incoming vs the
+/// account's own replies, which land as SENT), realistic category mix
+/// (CATEGORY_PERSONAL-heavy so the backfill priority pass has work to do),
+/// and dates quadratically weighted toward the recent past year.
+fn generate_plan(account: &str, count: usize, rng_seed: u64) -> Vec<PlannedMessage> {
+ let mut rng = StdRng::seed_from_u64(rng_seed);
+ let bodies = sample_bodies::load_sample_bodies();
+ let template_names = sample_bodies::TEMPLATE_NAMES;
+ let now = Utc::now();
+ let mut plan: Vec<PlannedMessage> = Vec::with_capacity(count);
+ let mut msg_index = 0usize;
+
+ while plan.len() < count {
+ let thread_len = if rng.random_range(0..100) < 30 {
+ rng.random_range(2..=5usize)
+ } else {
+ 1
+ };
+ let contact_idx = rng.random_range(0..FAKE_CONTACTS.len());
+ let (contact_addr, contact_name) = FAKE_CONTACTS[contact_idx];
+ let subject = SUBJECTS[rng.random_range(0..SUBJECTS.len())].to_string();
+ let category = match rng.random_range(0..100) {
+ 0..55 => "CATEGORY_PERSONAL",
+ 55..75 => "CATEGORY_UPDATES",
+ 75..90 => "CATEGORY_PROMOTIONS",
+ _ => "CATEGORY_FORUMS",
+ };
+ // Quadratic weighting: most threads start in the recent months.
+ let age_frac: f64 = rng.random::<f64>();
+ let mut date = now
+ - chrono::Duration::seconds((age_frac * age_frac * 365.0 * 86_400.0) as i64)
+ - chrono::Duration::seconds(rng.random_range(0..86_400));
+ let mut references: Vec<String> = Vec::new();
+
+ for reply_idx in 0..thread_len {
+ if plan.len() >= count {
+ break;
+ }
+ // First message is always incoming; replies alternate, so
+ // multi-message threads exercise SENT + conversation grouping.
+ let outgoing = reply_idx > 0 && reply_idx % 2 == 1;
+ let message_id = format!("<seed-{rng_seed}-{msg_index}@seed.macro-test.local>");
+ msg_index += 1;
+
+ let mut labels: Vec<&'static str> = Vec::new();
+ if outgoing {
+ labels.push("SENT");
+ } else {
+ labels.push("INBOX");
+ labels.push(category);
+ if rng.random_range(0..100) < 35 {
+ labels.push("UNREAD");
+ }
+ if rng.random_range(0..100) < 15 {
+ labels.push("IMPORTANT");
+ }
+ if rng.random_range(0..100) < 3 {
+ labels.push("STARRED");
+ }
+ }
+
+ let template = template_names[rng.random_range(0..template_names.len())];
+ let (text_body, _html) = &bodies[template];
+ // Vary body size: 1–4 copies of the template paragraph block.
+ let body = text_body.repeat(rng.random_range(1..=4));
+
+ let subject = if reply_idx == 0 {
+ subject.clone()
+ } else {
+ format!("Re: {subject}")
+ };
+ let (from, to) = if outgoing {
+ (
+ (account.to_string(), "Bigbox Test".to_string()),
+ (contact_addr.to_string(), contact_name.to_string()),
+ )
+ } else {
+ (
+ (contact_addr.to_string(), contact_name.to_string()),
+ (account.to_string(), "Bigbox Test".to_string()),
+ )
+ };
+
+ plan.push(PlannedMessage {
+ message_id: message_id.clone(),
+ // Reply offsets can walk a recent thread past current time, clamp so
+ // the fixture never contains future-dated mail.
+ date: date.min(now),
+ from,
+ to,
+ subject,
+ references: references.clone(),
+ labels,
+ body,
+ });
+ references.push(message_id);
+ date += chrono::Duration::seconds(rng.random_range(600..172_800));
+ }
+ }
+ plan
+}
+
+async fn seed(args: SeedArgs) -> anyhow::Result<()> {
+ use futures::StreamExt;
+
+ let api = std::sync::Arc::new(GmailApi::for_account(&args.account).await?);
+ let plan = generate_plan(&args.account, args.count, args.rng_seed);
+ let total = plan.len();
+ if args.offset >= total {
+ bail!("--offset {} is beyond the plan size {total}", args.offset);
+ }
+ tracing::info!(
+ account = %args.account,
+ total,
+ offset = args.offset,
+ rps = args.rps,
+ concurrency = args.concurrency,
+ eta_min = ((total - args.offset) as u64 / args.rps.max(1)) / 60,
+ "importing messages"
+ );
+
+ let url = std::sync::Arc::new(format!(
+ "{GMAIL_BASE}/messages/import?internalDateSource=dateHeader&neverMarkSpam=true"
+ ));
+ let started = Instant::now();
+ let pacer = std::sync::Arc::new(Pacer::new(args.rps));
+ let done = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
+
+ // Concurrent imports, paced at the start (Gmail threads by the References
+ // headers, so parent/reply arrival order does not matter). On any failure
+ // the earliest failed index is reported so `--offset` can resume.
+ let failures: Vec<usize> =
+ futures::stream::iter(plan.into_iter().enumerate().skip(args.offset))
+ .map(|(i, message)| {
+ let api = api.clone();
+ let url = url.clone();
+ let pacer = pacer.clone();
+ let done = done.clone();
+ async move {
+ pacer.wait_turn().await;
+ let body = serde_json::json!({
+ "raw": URL_SAFE_NO_PAD.encode(message.to_rfc2822()),
+ "labelIds": message.labels,
+ });
+ let result = api.call(reqwest::Method::POST, &url, Some(&body)).await;
+ match result {
+ Ok(_) => {
+ let count = done.fetch_add(1, std::sync::atomic::Ordering::Relaxed) + 1;
+ if count.is_multiple_of(250) {
+ let elapsed = started.elapsed().as_secs().max(1);
+ let rate = count as u64 / elapsed;
+ tracing::info!(
+ done = args.offset + count,
+ total,
+ rate_per_sec = rate,
+ eta_min =
+ (total - args.offset - count) as u64 / rate.max(1) / 60,
+ "import progress"
+ );
+ }
+ None
+ }
+ Err(e) => {
+ tracing::error!(error=?e, index = i, "import failed");
+ Some(i)
+ }
+ }
+ }
+ })
+ .buffer_unordered(args.concurrency)
+ .filter_map(futures::future::ready)
+ .collect()
+ .await;
+
+ if let Some(first_failed) = failures.iter().min() {
+ // Imports after the first failure may have succeeded (concurrency), so
+ // resuming at the first failed index would re-import those and create
+ // duplicates. `--offset` is only exact for a clean interruption
+ // (ctrl-c/crash); scattered failures need a reset.
+ bail!(
+ "{} of {total} imports failed (first at index {first_failed}); the mailbox now has \
+ gaps that `--offset` cannot resume without duplicates — run `gmail reset` and reseed \
+ (consider lower --rps/--concurrency: sustained failures usually mean quota contention, \
+ e.g. a connected local stack live-syncing this mailbox while it seeds)",
+ failures.len()
+ );
+ }
+ status(AccountArg {
+ account: args.account,
+ })
+ .await
+}
+
+async fn reset(args: AccountArg) -> anyhow::Result<()> {
+ let api = GmailApi::for_account(&args.account).await?;
+ let mut deleted = 0usize;
+ loop {
+ let list = api
+ .call(
+ reqwest::Method::GET,
+ &format!("{GMAIL_BASE}/messages?maxResults=500&includeSpamTrash=true"),
+ None,
+ )
+ .await?;
+ let ids: Vec<String> = list["messages"]
+ .as_array()
+ .map(|messages| {
+ messages
+ .iter()
+ .filter_map(|message| message["id"].as_str().map(str::to_string))
+ .collect()
+ })
+ .unwrap_or_default();
+ if ids.is_empty() {
+ break;
+ }
+ deleted += ids.len();
+ let body = serde_json::json!({ "ids": ids });
+ api.call(
+ reqwest::Method::POST,
+ &format!("{GMAIL_BASE}/messages/batchDelete"),
+ Some(&body),
+ )
+ .await?;
+ tracing::info!(deleted, "reset progress");
+ tokio::time::sleep(Duration::from_millis(500)).await;
+ }
+ tracing::info!(account = %args.account, deleted, "mailbox reset complete");
+ status(args).await
+}
+
+async fn status(args: AccountArg) -> anyhow::Result<()> {
+ let api = GmailApi::for_account(&args.account).await?;
+ let profile = api
+ .call(reqwest::Method::GET, &format!("{GMAIL_BASE}/profile"), None)
+ .await?;
+ tracing::info!(
+ email = %profile["emailAddress"].as_str().unwrap_or("?"),
+ messages_total = profile["messagesTotal"].as_u64().unwrap_or(0),
+ threads_total = profile["threadsTotal"].as_u64().unwrap_or(0),
+ history_id = %profile["historyId"].as_str().unwrap_or("?"),
+ "mailbox status"
+ );
+ Ok(())
+}
+
+/// A service-account access token, minted via the OAuth JWT-bearer grant and
+/// re-minted before expiry.
+struct SaToken {
+ http: reqwest::Client,
+ client_email: String,
+ encoding_key: jsonwebtoken::EncodingKey,
+ access_token: String,
+ minted_at: Instant,
+ /// Google-signed OIDC identity token presented to the webhook — the same
+ /// authentication a real Pub/Sub push subscription uses.
+ id_token: String,
+ id_token_audience: String,
+ id_minted_at: Instant,
+}
+
+impl SaToken {
+ async fn from_env(http: reqwest::Client) -> anyhow::Result<Self> {
+ let key_json = GmailForwarderSaKey::new()
+ .context("GMAIL_FORWARDER_SA_KEY is not set (use `just gmail …`)")?
+ .to_string();
+ let key: serde_json::Value =
+ serde_json::from_str(&key_json).context("GMAIL_FORWARDER_SA_KEY is not JSON")?;
+ let client_email = key["client_email"]
+ .as_str()
+ .context("SA key has no client_email")?
+ .to_string();
+ let encoding_key = jsonwebtoken::EncodingKey::from_rsa_pem(
+ key["private_key"]
+ .as_str()
+ .context("SA key has no private_key")?
+ .as_bytes(),
+ )
+ .context("SA private_key is not a valid RSA PEM")?;
+ let mut token = SaToken {
+ http,
+ client_email,
+ encoding_key,
+ access_token: String::new(),
+ minted_at: Instant::now(),
+ id_token: String::new(),
+ id_token_audience: String::new(),
+ id_minted_at: Instant::now(),
+ };
+ token.refresh().await?;
+ Ok(token)
+ }
+
+ /// Google-signed OIDC id token for `audience`, re-minted before expiry.
+ /// The JWT-bearer grant with a `target_audience` claim (instead of
+ /// `scope`) returns an identity token with iss=accounts.google.com and
+ /// aud=`audience` — which is exactly what the webhook's
+ /// `validate_google_token` verifies.
+ async fn webhook_bearer(&mut self, audience: &str) -> anyhow::Result<&str> {
+ if self.id_token_audience == audience
+ && self.id_minted_at.elapsed() < Duration::from_secs(50 * 60)
+ && !self.id_token.is_empty()
+ {
+ return Ok(&self.id_token);
+ }
+ #[derive(serde::Serialize)]
+ struct IdClaims<'a> {
+ iss: &'a str,
+ aud: &'a str,
+ target_audience: &'a str,
+ iat: u64,
+ exp: u64,
+ }
+ let now = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .expect("clock before unix epoch")
+ .as_secs();
+ let assertion = jsonwebtoken::encode(
+ &jsonwebtoken::Header::new(jsonwebtoken::Algorithm::RS256),
+ &IdClaims {
+ iss: &self.client_email,
+ aud: TOKEN_URL,
+ target_audience: audience,
+ iat: now,
+ exp: now + 3600,
+ },
+ &self.encoding_key,
+ )
+ .context("signing the id-token assertion")?;
+ let resp: serde_json::Value = self
+ .http
+ .post(TOKEN_URL)
+ .form(&[
+ ("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer"),
+ ("assertion", assertion.as_str()),
+ ])
+ .send()
+ .await
+ .context("id-token request failed")?
+ .json()
+ .await
+ .context("id-token response was not JSON")?;
+ self.id_token = resp["id_token"]
+ .as_str()
+ .with_context(|| format!("no id_token in response: {resp}"))?
+ .to_string();
+ self.id_token_audience = audience.to_string();
+ self.id_minted_at = Instant::now();
+ Ok(&self.id_token)
+ }
+
+ async fn refresh(&mut self) -> anyhow::Result<()> {
+ #[derive(serde::Serialize)]
+ struct Claims<'a> {
+ iss: &'a str,
+ scope: &'a str,
+ aud: &'a str,
+ iat: u64,
+ exp: u64,
+ }
+ let now = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .expect("clock before unix epoch")
+ .as_secs();
+ let assertion = jsonwebtoken::encode(
+ &jsonwebtoken::Header::new(jsonwebtoken::Algorithm::RS256),
+ &Claims {
+ iss: &self.client_email,
+ scope: "https://www.googleapis.com/auth/pubsub",
+ aud: TOKEN_URL,
+ iat: now,
+ exp: now + 3600,
+ },
+ &self.encoding_key,
+ )
+ .context("signing the service-account JWT")?;
+ let resp: serde_json::Value = self
+ .http
+ .post(TOKEN_URL)
+ .form(&[
+ ("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer"),
+ ("assertion", assertion.as_str()),
+ ])
+ .send()
+ .await
+ .context("SA token request failed")?
+ .json()
+ .await
+ .context("SA token response was not JSON")?;
+ self.access_token = resp["access_token"]
+ .as_str()
+ .with_context(|| format!("no access_token in SA token response: {resp}"))?
+ .to_string();
+ self.minted_at = Instant::now();
+ Ok(())
+ }
+
+ async fn bearer(&mut self) -> anyhow::Result<&str> {
+ // SA access tokens live an hour; re-mint with headroom.
+ if self.minted_at.elapsed() > Duration::from_secs(50 * 60) {
+ self.refresh().await?;
+ }
+ Ok(&self.access_token)
+ }
+}
+
+/// Create the pull subscription if it does not exist. Per-instance
+/// subscriptions let concurrent local stacks each receive every notification
+/// (a subscription is a queue, not a broadcast); the expiration policy lets
+/// Google garbage-collect subscriptions of instances nobody runs anymore.
+async fn ensure_subscription(
+ http: &reqwest::Client,
+ sa: &mut SaToken,
+ subscription: &str,
+ topic: &str,
+) -> anyhow::Result<()> {
+ let url = format!("https://pubsub.googleapis.com/v1/{subscription}");
+ let token = sa.bearer().await?.to_string();
+ let status = http
+ .get(&url)
+ .bearer_auth(&token)
+ .send()
+ .await
+ .context("subscription lookup failed")?
+ .status();
+ if status.is_success() {
+ return Ok(());
+ }
+ if status != reqwest::StatusCode::NOT_FOUND {
+ bail!("subscription lookup returned {status}");
+ }
+ let resp = http
+ .put(&url)
+ .bearer_auth(&token)
+ .json(&serde_json::json!({
+ "topic": topic,
+ "ackDeadlineSeconds": 30,
+ "expirationPolicy": { "ttl": "2678400s" },
+ }))
+ .send()
+ .await
+ .context("subscription create failed")?;
+ if !resp.status().is_success() {
+ let status = resp.status();
+ let body = resp.text().await.unwrap_or_default();
+ bail!(
+ "creating subscription {subscription} failed: {status}: {body} \
+ (the service account needs Pub/Sub Editor on the topic/project)"
+ );
+ }
+ tracing::info!(%subscription, %topic, "created pull subscription");
+ Ok(())
+}
+
+/// Pull Gmail watch notifications and re-deliver them to the local webhook in
+/// Pub/Sub push-envelope shape (what the webhook deserializes as
+/// `GmailInboxSyncPayload`). Messages are acked only after the webhook accepts
+/// them, so a stack that is down redelivers instead of losing sync events.
+async fn forward(args: ForwardArgs) -> anyhow::Result<()> {
+ let http = http_client()?;
+ let mut sa = SaToken::from_env(http.clone()).await?;
+ ensure_subscription(&http, &mut sa, &args.subscription, &args.topic).await?;
+ let pull_url = format!(
+ "https://pubsub.googleapis.com/v1/{}:pull",
+ args.subscription
+ );
+ let ack_url = format!(
+ "https://pubsub.googleapis.com/v1/{}:acknowledge",
+ args.subscription
+ );
+ tracing::info!(subscription = %args.subscription, target = %args.target, "forwarding gmail notifications (ctrl-c to stop)");
+
+ let mut forwarded = 0u64;
+ loop {
+ let token = sa.bearer().await?;
+ let pull: serde_json::Value = match http
+ .post(&pull_url)
+ .bearer_auth(token)
+ .json(&serde_json::json!({ "maxMessages": 25 }))
+ .send()
+ .await
+ {
+ Ok(resp) if resp.status().is_success() => {
+ resp.json().await.unwrap_or(serde_json::Value::Null)
+ }
+ Ok(resp) => {
+ tracing::warn!(status = %resp.status(), "pull failed, backing off");
+ tokio::time::sleep(Duration::from_secs(5)).await;
+ continue;
+ }
+ Err(e) => {
+ tracing::warn!(error = ?e, "pull error, backing off");
+ tokio::time::sleep(Duration::from_secs(5)).await;
+ continue;
+ }
+ };
+ let received = pull["receivedMessages"]
+ .as_array()
+ .cloned()
+ .unwrap_or_default();
+ if received.is_empty() {
+ tokio::time::sleep(Duration::from_secs(2)).await;
+ continue;
+ }
+
+ let mut ack_ids: Vec<String> = Vec::new();
+ for entry in &received {
+ // Pub/Sub pull returns STANDARD base64 but the webhook's
+ // deserializer strictly decodes URL_SAFE (the push alphabet) —
+ // transcode so payloads containing '+'/'/' can't poison the queue.
+ let data = entry["message"]["data"].as_str().unwrap_or_default();
+ let decoded = match STANDARD.decode(data) {
+ Ok(bytes) => bytes,
+ Err(e) => {
+ tracing::warn!(error = ?e, "notification data is not base64; acking to discard");
+ if let Some(ack) = entry["ackId"].as_str() {
+ ack_ids.push(ack.to_string());
+ }
+ continue;
+ }
+ };
+ let envelope = serde_json::json!({
+ "message": {
+ "data": URL_SAFE.encode(&decoded),
+ "messageId": entry["message"]["messageId"],
+ "publishTime": entry["message"]["publishTime"],
+ },
+ "subscription": args.subscription,
+ });
+ let webhook_token = sa.webhook_bearer(&args.webhook_audience).await?.to_string();
+ match http
+ .post(&args.target)
+ .bearer_auth(webhook_token)
+ .json(&envelope)
+ .send()
+ .await
+ {
+ Ok(resp) if resp.status().is_success() => {
+ if let Some(ack) = entry["ackId"].as_str() {
+ ack_ids.push(ack.to_string());
+ }
+ forwarded += 1;
+ let notification = String::from_utf8_lossy(&decoded);
+ tracing::info!(forwarded, %notification, "delivered to webhook");
+ }
+ Ok(resp) => {
+ tracing::warn!(status = %resp.status(), "webhook rejected notification; leaving unacked");
+ }
+ Err(e) => {
+ tracing::warn!(error = ?e, "webhook unreachable; leaving unacked");
+ }
+ }
+ }
+ if !ack_ids.is_empty() {
+ let token = sa.bearer().await?;
+ if let Err(e) = http
+ .post(&ack_url)
+ .bearer_auth(token)
+ .json(&serde_json::json!({ "ackIds": ack_ids }))
+ .send()
+ .await
+ {
+ tracing::warn!(error = ?e, "ack failed; notifications will redeliver");
+ }
+ }
+ }
+}
diff --git a/tooling/seed_cli/src/entity/gmail/test.rs b/tooling/seed_cli/src/entity/gmail/test.rs
new file mode 100644
index 0000000000..5f252fd3de
--- /dev/null
+++ b/tooling/seed_cli/src/entity/gmail/test.rs
@@ -0,0 +1,23 @@
+use super::*;
+
+#[test]
+fn plan_is_deterministic_and_never_future_dated() {
+ let now = Utc::now();
+ let a = generate_plan("[email protected]", 500, 42);
+ let b = generate_plan("[email protected]", 500, 42);
+ assert_eq!(a.len(), 500);
+ for (x, y) in a.iter().zip(&b) {
+ assert_eq!(
+ x.message_id, y.message_id,
+ "same seed must give the same plan"
+ );
+ assert_eq!(x.subject, y.subject);
+ }
+ assert!(
+ a.iter()
+ .all(|m| m.date <= now + chrono::Duration::seconds(5)),
+ "no message may be dated in the future"
+ );
+ let sent = a.iter().filter(|m| m.labels.contains(&"SENT")).count();
+ assert!(sent > 0, "threads must include outgoing replies");
+}
diff --git a/tooling/seed_cli/src/entity/mod.rs b/tooling/seed_cli/src/entity/mod.rs
index 7ccef70785..00e71f340f 100644
--- a/tooling/seed_cli/src/entity/mod.rs
+++ b/tooling/seed_cli/src/entity/mod.rs
@@ -4,6 +4,7 @@ pub mod channel;
pub mod channel_message;
pub mod document;
pub mod email;
+pub mod gmail;
pub mod scenario;
pub mod user;
@@ -24,6 +25,8 @@ pub enum EntityCommand {
Document(document::DocumentArgs),
/// Manage email seed data
Email(email::EmailArgs),
+ /// Seed real Gmail test mailboxes via the Gmail API
+ Gmail(gmail::GmailArgs),
/// Apply predefined seed scenarios
Scenario(scenario::ScenarioArgs),
}
@@ -54,6 +57,7 @@ impl EntityCommand {
EntityCommand::ChannelMessage(args) => args.execute(ctx).await,
EntityCommand::Document(args) => args.execute(ctx).await,
EntityCommand::Email(args) => args.execute(ctx).await,
+ EntityCommand::Gmail(args) => args.execute().await,
EntityCommand::Scenario(args) => args.execute(ctx).await,
}
}
diff --git a/tooling/seed_cli/src/main.rs b/tooling/seed_cli/src/main.rs
index 8ba06f6318..75724a572c 100644
--- a/tooling/seed_cli/src/main.rs
+++ b/tooling/seed_cli/src/main.rs
@@ -34,6 +34,11 @@ pub async fn main() -> anyhow::Result<()> {
// Force to use local tracing
MacroEntrypoint::new(Environment::Local).init();
let cli = Cli::parse();
+ // The gmail entity talks only to Google — dispatch it before the required
+ // env vars / database connection so it works without the local stack.
+ if let EntityCommand::Gmail(args) = cli.command {
+ return args.execute().await;
+ }
let env_vars = EnvVars::new()?;
cli.command.validate_environment(&env_vars)?;
tracing::trace!("initializing");
@@ -51,8 +56,7 @@ pub async fn main() -> anyhow::Result<()> {
.context("could not connect to db")?;
tracing::trace!("initialized db");
- let fusionauth_client = FusionAuthClient::new_for_local_instance(
- env_vars.fusionauth_tenant_id.to_string(),
+ let fusionauth_client = FusionAuthClient::new(
env_vars.fusionauth_api_key_secret_key.to_string(),
env_vars.fusionauth_client_id.to_string(),
env_vars.fusionauth_client_secret_key.to_string(),
diff --git a/tooling/xtask/crates/xtask_local/src/local/env_layer.rs b/tooling/xtask/crates/xtask_local/src/local/env_layer.rs
index 20227761a8..667dddb4b9 100644
--- a/tooling/xtask/crates/xtask_local/src/local/env_layer.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/env_layer.rs
@@ -42,6 +42,7 @@ pub fn resolve(
instance: &Instance,
no_doppler: bool,
env_file: Option<&Path>,
+ static_frontend: bool,
) -> Result<ResolvedEnv> {
// Base = Doppler (`lcl_personal`/`dev_personal`); it supplies the
// integration/secret config services require. For local we then overlay the
@@ -57,7 +58,7 @@ pub fn resolve(
pull_doppler(spec.doppler_config, &mut env)?
};
if spec.overlay_local_env {
- for (k, v) in local_env::LocalEnv::for_instance(mode, instance).to_env() {
+ for (k, v) in local_env::LocalEnv::for_instance(mode, instance, static_frontend).to_env() {
env.insert(k, v);
}
// Opt-in local trace export: point services at the local OTLP collector
diff --git a/tooling/xtask/crates/xtask_local/src/local/fusionauth.rs b/tooling/xtask/crates/xtask_local/src/local/fusionauth.rs
index 03da067469..43c78ee9c0 100644
--- a/tooling/xtask/crates/xtask_local/src/local/fusionauth.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/fusionauth.rs
@@ -8,32 +8,29 @@ use anyhow::{Context, Result};
use super::instance::{Instance, Port};
use super::{gen_compose, identity, kickstart, stage::Stage};
-/// The local populate-JWT lambda body, inlined into `kickstart.json`.
-///
-/// LOCAL-ONLY variant of the production populate-JWT lambda. Production enriches
-/// the JWT by calling authentication-service over HTTP, but Lambda HTTP Connect
-/// is a licensed FusionAuth feature that silently fails without a Reactor
-/// license. Local runs unlicensed, so we derive the claims instead: password
-/// users follow the `macro|<email>` convention (see `seed_cli`) and no Google
-/// IdP is configured locally, so every local user is a `macro|` user.
-/// Divergence from production: `root_macro_id` / `macro_organization_id` are
-/// never populated — org-scoped JWT flows need the licensed lambda + a license.
-///
-/// Inlined (not `include_str!`) because the canonical `.js` lives under
-/// `infra/` where a blanket `*.js` gitignore makes it untracked — a fresh
-/// checkout / CI / devcontainer wouldn't have it, breaking the build. Kept
-/// comment-free so it survives FusionAuth flattening the body to one line.
-const POPULATE_JWT_LAMBDA: &str = "function populate(jwt, user, _registration) {
- jwt.fusion_user_id = user.id;
- jwt.email = user.email;
- jwt.macro_user_id = 'macro|' + user.email;
-}";
+/// The FusionAuth lambda sources, read from the tracked templates at
+/// generation time (anchored on [`xtask_paths::repo_root`], so any cwd works).
+/// `populate_jwt_local.js` is the unlicensed local variant (see its header);
+/// the reconcile lambda is the same file production deploys via Pulumi.
+const POPULATE_JWT_LAMBDA: xtask_paths::RepoFile<'static> =
+ xtask_paths::RepoFile::new("infra/stacks/fusionauth-instance/templates/populate_jwt_local.js");
+const RECONCILE_LAMBDA: xtask_paths::RepoFile<'static> = xtask_paths::RepoFile::new(
+ "infra/stacks/fusionauth-instance/templates/reconcile_secondary_idp_link.js",
+);
+
+fn read_lambda(file: xtask_paths::RepoFile<'static>) -> Result<String> {
+ let path = xtask_paths::repo_root().join(file.as_str());
+ std::fs::read_to_string(&path).with_context(|| format!("reading {}", path.display()))
+}
/// Generate `kickstart.json` into the instance's kickstart dir, which the
/// FusionAuth container mounts. The kickstart is pure identity-provider config:
/// run_local pre-seeds no users — passwordless login auto-creates any user on
-/// demand.
-pub fn write_kickstart(instance: &Instance) -> Result<()> {
+/// demand. `google` (from the resolved run env) additionally configures the
+/// `google`/`google_gmail` OIDC IdPs so the email connect flows work locally;
+/// the generated file is gitignored, and the init-snapshot key hashes it, so
+/// adding/removing the Google client re-inits the stack automatically.
+pub fn write_kickstart(instance: &Instance, google: Option<&kickstart::GoogleIdp>) -> Result<()> {
let dir = gen_compose::kickstart_dir(instance);
std::fs::create_dir_all(&dir)
.with_context(|| format!("creating kickstart dir {}", dir.display()))?;
@@ -41,7 +38,9 @@ pub fn write_kickstart(instance: &Instance) -> Result<()> {
let doc = kickstart::build(
instance.port(Port::Frontend),
instance.port(Port::Auth),
- POPULATE_JWT_LAMBDA,
+ &read_lambda(POPULATE_JWT_LAMBDA)?,
+ &read_lambda(RECONCILE_LAMBDA)?,
+ google,
);
let json = serde_json::to_string_pretty(&doc)? + "\n";
std::fs::write(dir.join("kickstart.json"), json)
diff --git a/tooling/xtask/crates/xtask_local/src/local/gen_compose.rs b/tooling/xtask/crates/xtask_local/src/local/gen_compose.rs
index 09d8f9d844..fabcb1ce5c 100644
--- a/tooling/xtask/crates/xtask_local/src/local/gen_compose.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/gen_compose.rs
@@ -62,6 +62,7 @@ pub fn generate(
instance: &Instance,
binaries: &BinariesDir,
static_frontend: bool,
+ gmail_forwarder: bool,
) -> Result<PathBuf> {
let mut services: IndexMap<String, Option<dct::Service>> = IndexMap::new();
let mounts = binaries.compose_mounts();
@@ -96,6 +97,41 @@ pub fn generate(
if mode.spec().runs_local_infra {
add_local_infra(&mut services, instance, static_frontend);
}
+ // Live Gmail sync: forward watch notifications from the instance's own
+ // Pub/Sub subscription to the email service's webhook. Per-instance
+ // subscriptions (created by the forwarder on startup) let concurrent
+ // stacks sync independently — a subscription is a queue, not a broadcast,
+ // so sharing one would make instances steal each other's notifications.
+ // Gated on the SA key being present in the resolved env.
+ if gmail_forwarder && mode.spec().runs_local_infra {
+ services.insert(
+ "gmail_forwarder".to_string(),
+ Some(dct::Service {
+ image: Some(RUNTIME_IMAGE_TAG.to_string()),
+ volumes: mounts.iter().cloned().map(dct::Volumes::Simple).collect(),
+ command: Some(dct::Command::Args(
+ [
+ "/app/out/seed_cli",
+ "gmail",
+ "forward",
+ "--target",
+ "http://email-service:8080/gmail/webhook",
+ "--subscription",
+ &format!(
+ "projects/macro-email-testing/subscriptions/gmail-local-watch-{}",
+ instance.name()
+ ),
+ ]
+ .iter()
+ .map(|s| s.to_string())
+ .collect(),
+ )),
+ env_file: Some(dct::StringOrList::Simple("${MACRO_ENV_FILE}".to_string())),
+ networks: net_aliases(&[("services", &["gmail-forwarder"])]),
+ ..Default::default()
+ }),
+ );
+ }
let compose = dct::Compose {
services: dct::Services(services),
diff --git a/tooling/xtask/crates/xtask_local/src/local/identity.rs b/tooling/xtask/crates/xtask_local/src/local/identity.rs
index 632f186135..5b6bcab098 100644
--- a/tooling/xtask/crates/xtask_local/src/local/identity.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/identity.rs
@@ -29,7 +29,9 @@ pub const POPULATE_JWT_LAMBDA_ID: &str = "a7f3e8d2-4b91-4c5a-9e6f-1a2b3c4d5e6f";
/// create-application step fail with `[duplicate]applicationId`.
pub const APPLICATION_ID: &str = "22222222-2222-4222-8222-222222222222";
-/// A fixed local tenant id (deterministic, local-only).
+/// A fixed local tenant id (deterministic, local-only). This is FusionAuth's
+/// built-in default tenant, pinned via the kickstart `defaultTenantId`
+/// variable and reconfigured in place — local is single-tenant by design.
pub const TENANT_ID: &str = "11111111-1111-4111-8111-111111111111";
/// A fixed OAuth client secret (deterministic, local-only).
@@ -41,6 +43,19 @@ pub const ISSUER: &str = "local.macro.com";
/// Fixed id for the passwordless-login email template the kickstart creates.
pub const PASSWORDLESS_EMAIL_TEMPLATE_ID: &str = "33333333-3333-4333-8333-333333333333";
+/// Fixed id for the `google` (plain login) OIDC identity provider. Only created
+/// when a Google OAuth client is configured (see `kickstart::GoogleIdp`).
+pub const GOOGLE_IDP_ID: &str = "44444444-4444-4444-8444-444444444444";
+
+/// Fixed id for the `google_gmail` (Gmail-scoped) OIDC identity provider.
+/// `authentication_service` resolves it by name, so the id only has to be
+/// stable, not shared with dev/prod.
+pub const GOOGLE_GMAIL_IDP_ID: &str = "55555555-5555-4555-8555-555555555555";
+
+/// Fixed id for the reconcile lambda attached to `google_gmail` (blocks
+/// sign-in with a Google account that is linked as a secondary inbox).
+pub const RECONCILE_LAMBDA_ID: &str = "66666666-6666-4666-8666-666666666666";
+
/// Local from-address for FusionAuth-sent mail (lands in Mailpit).
pub const MAIL_FROM: &str = "[email protected]";
diff --git a/tooling/xtask/crates/xtask_local/src/local/inventory.rs b/tooling/xtask/crates/xtask_local/src/local/inventory.rs
index d97d4f9add..bbaea699ea 100644
--- a/tooling/xtask/crates/xtask_local/src/local/inventory.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/inventory.rs
@@ -169,6 +169,20 @@ pub const RUST_SERVICES: &[RustService] = &[
opt_in: false,
no_default_features: false,
},
+ RustService {
+ // Not a service: the seed CLI binary, shipped into /app/out so the
+ // gmail_forwarder sidecar (a bespoke gen_compose block, hence no
+ // modes) can run `seed_cli gmail forward` inside the stack.
+ compose_name: "gmail_forwarder",
+ cargo_bin: "seed_cli",
+ package: "seed_cli",
+ host_port: None,
+ path_prefix: None,
+ is_websocket: false,
+ modes: &[],
+ opt_in: false,
+ no_default_features: false,
+ },
RustService {
compose_name: "notification_service",
cargo_bin: "notification_service",
diff --git a/tooling/xtask/crates/xtask_local/src/local/inventory/test.rs b/tooling/xtask/crates/xtask_local/src/local/inventory/test.rs
index 29d11cb014..fa89dfd142 100644
--- a/tooling/xtask/crates/xtask_local/src/local/inventory/test.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/inventory/test.rs
@@ -3,10 +3,12 @@ use super::*;
#[test]
fn local_binaries_are_unique_and_complete() {
let bins = local_binaries();
- // 13 distinct binaries (the bundled set, including the local-only
- // search_processing_service).
- assert_eq!(bins.len(), 13, "{bins:?}");
+ // 14 distinct binaries (the bundled set, including the local-only
+ // search_processing_service and the seed_cli shipped for the
+ // gmail_forwarder sidecar).
+ assert_eq!(bins.len(), 14, "{bins:?}");
assert!(bins.contains(&"pubsub_workers"));
+ assert!(bins.contains(&"seed_cli"));
assert!(bins.contains(&"document_upload_finalizer_local_worker"));
assert!(bins.contains(&"search_processing_service"));
let mut sorted = bins.clone();
diff --git a/tooling/xtask/crates/xtask_local/src/local/kickstart.rs b/tooling/xtask/crates/xtask_local/src/local/kickstart.rs
index e255a9c237..ad91a9e920 100644
--- a/tooling/xtask/crates/xtask_local/src/local/kickstart.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/kickstart.rs
@@ -9,13 +9,59 @@
//! (after the app it registers against exists); passwordless login auto-creates
//! all other users on demand.
+use std::collections::BTreeMap;
+
use serde_json::{Value, json};
use super::identity;
+#[cfg(test)]
+mod test;
+
+/// The Google OAuth web client the local `google`/`google_gmail` OIDC identity
+/// providers authenticate against (the Internal client in the
+/// `macro-email-testing` GCP project — see the macro-2634 proposal). Optional:
+/// without it the kickstart is unchanged and the email connect flows stay
+/// unreachable locally, exactly as before.
+pub struct GoogleIdp {
+ pub client_id: String,
+ pub client_secret: String,
+}
+
+impl GoogleIdp {
+ /// Extract the Google client from the resolved run env (Doppler supplies
+ /// `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET_KEY`; in local mode
+ /// authentication_service uses the latter directly as the secret value).
+ ///
+ /// The `GOCSPX-` check is load-bearing, not cosmetic: older Doppler local
+ /// configs carry a Secrets-Manager key *name* (`google-client-secret-dev`)
+ /// in `GOOGLE_CLIENT_SECRET_KEY`. Real Google web-client secrets all carry
+ /// the `GOCSPX-` prefix; creating the IdPs with the placeholder would bake
+ /// a broken FusionAuth config into the init snapshot.
+ pub fn from_env(env: &BTreeMap<String, String>) -> Option<Self> {
+ let client_id = env.get("GOOGLE_CLIENT_ID")?.trim().to_string();
+ let client_secret = env.get("GOOGLE_CLIENT_SECRET_KEY")?.trim().to_string();
+ if client_id.is_empty() || !client_secret.starts_with("GOCSPX-") {
+ return None;
+ }
+ Some(GoogleIdp {
+ client_id,
+ client_secret,
+ })
+ }
+}
+
/// Build the kickstart document. `lambda_body` is the JS source of
-/// `populate_jwt_local.js`; redirect URLs are templated from the instance ports.
-pub fn build(frontend_port: u16, auth_port: u16, lambda_body: &str) -> Value {
+/// `populate_jwt_local.js`; `reconcile_lambda_body` is the reconcile lambda
+/// attached to `google_gmail` (only used when `google` is configured); redirect
+/// URLs are templated from the instance ports.
+pub fn build(
+ frontend_port: u16,
+ auth_port: u16,
+ lambda_body: &str,
+ reconcile_lambda_body: &str,
+ google: Option<&GoogleIdp>,
+) -> Value {
let app_id = identity::APPLICATION_ID;
let tenant_id = identity::TENANT_ID;
let key_id = identity::JWT_SIGNING_KEY_ID;
@@ -39,7 +85,7 @@ pub fn build(frontend_port: u16, auth_port: u16, lambda_body: &str) -> Value {
// tenant marks `user.create` as AbsoluteMajority, so once the global
// user.create webhook exists, creating a user would roll back unless
// auth-service returns 2xx — which it isn't guaranteed to during kickstart.
- let requests = vec![
+ let mut requests = vec![
// 1. HS256 signing key.
json!({
"method": "POST",
@@ -79,9 +125,15 @@ pub fn build(frontend_port: u16, auth_port: u16, lambda_body: &str) -> Value {
}}
}),
// 4. Tenant — with SMTP pointed at Mailpit + the passwordless template,
- // so FusionAuth-sent passwordless codes land in Mailpit.
+ // so FusionAuth-sent passwordless codes land in Mailpit. PATCH, not
+ // POST: `variables.defaultTenantId` (below) pins FusionAuth's built-in
+ // default tenant to our fixed id, and this request reconfigures that
+ // tenant in place. Local stays single-tenant this way — a second
+ // tenant would force the tenant header onto every API call, and the
+ // identity-provider search API returns nothing when that header is
+ // present.
json!({
- "method": "POST",
+ "method": "PATCH",
"url": format!("/api/tenant/{tenant_id}"),
"body": { "tenant": {
"name": "Macro Local",
@@ -211,10 +263,80 @@ pub fn build(frontend_port: u16, auth_port: u16, lambda_body: &str) -> Value {
}),
];
+ // Google OIDC identity providers — only when a real Google client is
+ // configured (see `GoogleIdp::from_env`). Mirrors the dev instance's IdP
+ // config field-for-field (generic OIDC, NOT FusionAuth's built-in Google
+ // type: auth-service and the IdP must share the same OAuth client, and the
+ // endpoints stay per-IdP config). Appended last: `applicationConfiguration`
+ // references the application, which must already exist.
+ if let Some(google) = google {
+ let oauth2_base = |scope: &str| {
+ json!({
+ "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth?prompt=consent&access_type=offline",
+ "token_endpoint": "https://oauth2.googleapis.com/token",
+ "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
+ "client_id": google.client_id.as_str(),
+ "client_secret": google.client_secret.as_str(),
+ "clientAuthenticationMethod": "client_secret_basic",
+ "scope": scope,
+ "uniqueIdClaim": "sub",
+ "emailClaim": "email",
+ "emailVerifiedClaim": "email_verified",
+ "usernameClaim": "preferred_username",
+ })
+ };
+ let app_config = json!({
+ identity::APPLICATION_ID: { "enabled": true, "createRegistration": true }
+ });
+ requests.push(json!({
+ "method": "POST",
+ "url": format!("/api/lambda/{}", identity::RECONCILE_LAMBDA_ID),
+ "body": { "lambda": {
+ "id": identity::RECONCILE_LAMBDA_ID,
+ "name": "Reconcile Secondary IdP Link (local)",
+ "type": "OpenIDReconcile",
+ "enabled": true,
+ "body": reconcile_lambda_body,
+ }}
+ }));
+ requests.push(json!({
+ "method": "POST",
+ "url": format!("/api/identity-provider/{}", identity::GOOGLE_IDP_ID),
+ "body": { "identityProvider": {
+ "type": "OpenIDConnect",
+ "name": "google",
+ "enabled": true,
+ "debug": true,
+ "buttonText": "Google",
+ "linkingStrategy": "LinkByEmail",
+ "oauth2": oauth2_base("openid profile email"),
+ "applicationConfiguration": app_config.clone(),
+ }}
+ }));
+ requests.push(json!({
+ "method": "POST",
+ "url": format!("/api/identity-provider/{}", identity::GOOGLE_GMAIL_IDP_ID),
+ "body": { "identityProvider": {
+ "type": "OpenIDConnect",
+ "name": "google_gmail",
+ "enabled": true,
+ "debug": true,
+ "buttonText": "GoogleGmail",
+ "linkingStrategy": "LinkByEmail",
+ "lambdaConfiguration": { "reconcileId": identity::RECONCILE_LAMBDA_ID },
+ "oauth2": oauth2_base("openid profile email https://www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/contacts.readonly https://www.googleapis.com/auth/contacts.other.readonly https://www.googleapis.com/auth/gmail.settings.basic"),
+ "applicationConfiguration": app_config,
+ }}
+ }));
+ }
+
json!({
"//": "GENERATED by xtask (cargo x run-local). Deterministic local FusionAuth bootstrap. Do not edit.",
"apiKeys": [ { "key": identity::FUSIONAUTH_API_KEY, "description": "Local Development API Key" } ],
- "variables": {},
+ // `defaultTenantId` renames FusionAuth's built-in default tenant to our
+ // fixed id at schema-creation time, so the tenant request above can
+ // adopt it instead of creating a second tenant.
+ "variables": { "defaultTenantId": identity::TENANT_ID },
"requests": requests,
})
}
diff --git a/tooling/xtask/crates/xtask_local/src/local/kickstart/test.rs b/tooling/xtask/crates/xtask_local/src/local/kickstart/test.rs
new file mode 100644
index 0000000000..dcba8a6e7a
--- /dev/null
+++ b/tooling/xtask/crates/xtask_local/src/local/kickstart/test.rs
@@ -0,0 +1,139 @@
+use super::*;
+
+fn env(pairs: &[(&str, &str)]) -> BTreeMap<String, String> {
+ pairs
+ .iter()
+ .map(|(k, v)| (k.to_string(), v.to_string()))
+ .collect()
+}
+
+#[test]
+fn google_idp_requires_a_real_client_secret() {
+ // The legacy Doppler placeholder is a Secrets-Manager key NAME, not a
+ // secret — building IdPs from it would bake a broken FusionAuth config
+ // into the init snapshot.
+ assert!(
+ GoogleIdp::from_env(&env(&[
+ ("GOOGLE_CLIENT_ID", "abc.apps.googleusercontent.com"),
+ ("GOOGLE_CLIENT_SECRET_KEY", "google-client-secret-dev"),
+ ]))
+ .is_none()
+ );
+ assert!(GoogleIdp::from_env(&env(&[])).is_none());
+ assert!(
+ GoogleIdp::from_env(&env(&[
+ ("GOOGLE_CLIENT_ID", ""),
+ ("GOOGLE_CLIENT_SECRET_KEY", "GOCSPX-real"),
+ ]))
+ .is_none()
+ );
+
+ let ok = GoogleIdp::from_env(&env(&[
+ ("GOOGLE_CLIENT_ID", "abc.apps.googleusercontent.com"),
+ ("GOOGLE_CLIENT_SECRET_KEY", "GOCSPX-real"),
+ ]))
+ .expect("a real client id + GOCSPX secret must parse");
+ assert_eq!(ok.client_id, "abc.apps.googleusercontent.com");
+ assert_eq!(ok.client_secret, "GOCSPX-real");
+}
+
+#[test]
+fn kickstart_without_google_has_no_idp_requests() {
+ let doc = build(
+ 3000,
+ 8080,
+ "function populate() {}",
+ "function reconcile() {}",
+ None,
+ );
+ let urls: Vec<&str> = doc["requests"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|r| r["url"].as_str().unwrap())
+ .collect();
+ assert!(
+ !urls.iter().any(|u| u.contains("/api/identity-provider")),
+ "no Google client -> no IdP requests: {urls:?}"
+ );
+}
+
+#[test]
+fn kickstart_with_google_adds_lambda_and_both_idps_after_the_application() {
+ let google = GoogleIdp {
+ client_id: "abc.apps.googleusercontent.com".into(),
+ client_secret: "GOCSPX-real".into(),
+ };
+ let doc = build(
+ 3000,
+ 8080,
+ "function populate() {}",
+ "function reconcile() {}",
+ Some(&google),
+ );
+ let requests = doc["requests"].as_array().unwrap();
+
+ let pos = |needle: &str| {
+ requests
+ .iter()
+ .position(|r| r["url"].as_str().unwrap().contains(needle))
+ .unwrap_or_else(|| panic!("missing request for {needle}"))
+ };
+ let app = pos(identity::APPLICATION_ID);
+ let reconcile = pos(identity::RECONCILE_LAMBDA_ID);
+ let google_idp = pos(identity::GOOGLE_IDP_ID);
+ let gmail_idp = pos(identity::GOOGLE_GMAIL_IDP_ID);
+ assert!(app < reconcile && reconcile < google_idp && google_idp < gmail_idp);
+
+ let gmail = &requests[gmail_idp]["body"]["identityProvider"];
+ assert_eq!(gmail["name"], "google_gmail");
+ assert_eq!(
+ gmail["lambdaConfiguration"]["reconcileId"],
+ identity::RECONCILE_LAMBDA_ID
+ );
+ assert_eq!(
+ gmail["oauth2"]["client_id"],
+ "abc.apps.googleusercontent.com"
+ );
+ assert!(
+ gmail["oauth2"]["scope"]
+ .as_str()
+ .unwrap()
+ .contains("gmail.modify")
+ );
+ assert_eq!(
+ gmail["applicationConfiguration"][identity::APPLICATION_ID]["createRegistration"],
+ true
+ );
+
+ let plain = &requests[google_idp]["body"]["identityProvider"];
+ assert_eq!(plain["name"], "google");
+ assert_eq!(plain["oauth2"]["scope"], "openid profile email");
+ assert!(plain["lambdaConfiguration"].is_null());
+}
+
+#[test]
+fn kickstart_adopts_the_default_tenant() {
+ let doc = build(
+ 3000,
+ 8080,
+ "function populate() {}",
+ "function reconcile() {}",
+ None,
+ );
+ assert_eq!(
+ doc["variables"]["defaultTenantId"],
+ identity::TENANT_ID,
+ "the built-in default tenant must be pinned to the fixed local id"
+ );
+ let tenant = doc["requests"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .find(|r| r["url"].as_str().unwrap() == format!("/api/tenant/{}", identity::TENANT_ID))
+ .expect("missing tenant request");
+ assert_eq!(
+ tenant["method"], "PATCH",
+ "the tenant is reconfigured in place, not created — local stays single-tenant"
+ );
+}
diff --git a/tooling/xtask/crates/xtask_local/src/local/local_env.rs b/tooling/xtask/crates/xtask_local/src/local/local_env.rs
index 776e229476..17c614048e 100644
--- a/tooling/xtask/crates/xtask_local/src/local/local_env.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/local_env.rs
@@ -21,6 +21,12 @@ use super::{Mode, identity, resources};
pub struct LocalEnv {
environment: &'static str,
project_name: String,
+ /// Where the browser-facing app lives: the proxy (static bundle at
+ /// `/app`) or the bun dev server. `default_redirect_url()` in
+ /// authentication_service sends post-login browsers to
+ /// `http://localhost:{FRONTEND_PORT}`, so this must track the serving
+ /// mode or every OAuth signup dead-ends on an unused port.
+ frontend_port: u16,
infra: InfraEnv,
storage: StorageEnv,
queues: QueueEnv,
@@ -32,12 +38,17 @@ pub struct LocalEnv {
impl LocalEnv {
/// Build the local env for `instance` in `Local` mode (dev sources its env
/// from Doppler, not here).
- pub fn for_instance(mode: Mode, instance: &Instance) -> Self {
+ pub fn for_instance(mode: Mode, instance: &Instance, static_frontend: bool) -> Self {
let name = instance.name();
LocalEnv {
// Both local flavors run against local infra (`local` env defaults).
environment: mode.environment_var(),
project_name: instance.project_name().to_string(),
+ frontend_port: if static_frontend {
+ instance.port(Port::Proxy)
+ } else {
+ instance.port(Port::Frontend)
+ },
infra: InfraEnv::local(),
storage: StorageEnv::local(),
queues: QueueEnv::local(),
@@ -53,6 +64,7 @@ impl LocalEnv {
env.insert("ENVIRONMENT".into(), self.environment.into());
env.insert("COMPOSE_PROJECT_NAME".into(), self.project_name.clone());
env.insert("PORT".into(), "8080".into());
+ env.insert("FRONTEND_PORT".into(), self.frontend_port.to_string());
self.infra.write(&mut env);
self.storage.write(&mut env);
self.queues.write(&mut env);
@@ -116,6 +128,19 @@ impl InfraEnv {
"OVERRIDE_DOCUMENT_STORAGE_SERVICE_URL".into(),
"http://document-storage-service:8080".into(),
);
+ // Same failure mode for the email connect flows: without these,
+ // first-inbox provisioning (auth-service → `/email/init`) and Gmail
+ // token fetches (email-service → `/internal/google_access_token`)
+ // fail with connection errors. (Plain `EMAIL_SERVICE_URL` in Doppler
+ // is ignored — macro_service_urls only honors the `OVERRIDE_` prefix.)
+ env.insert(
+ "OVERRIDE_EMAIL_SERVICE_URL".into(),
+ "http://email-service:8080".into(),
+ );
+ env.insert(
+ "OVERRIDE_AUTH_SERVICE_URL".into(),
+ "http://authentication-service:8080".into(),
+ );
// Dummy creds: the SDK talks to LocalStack, never real AWS.
env.insert("AWS_ACCESS_KEY_ID".into(), "test".into());
env.insert("AWS_SECRET_ACCESS_KEY".into(), "test".into());
@@ -287,7 +312,6 @@ impl FusionAuthEnv {
"FUSIONAUTH_API_KEY_SECRET_KEY".into(),
identity::FUSIONAUTH_API_KEY.into(),
);
- env.insert("FUSIONAUTH_TENANT_ID".into(), identity::TENANT_ID.into());
env.insert(
"FUSIONAUTH_CLIENT_ID".into(),
identity::APPLICATION_ID.into(),
diff --git a/tooling/xtask/crates/xtask_local/src/local/local_env/test.rs b/tooling/xtask/crates/xtask_local/src/local/local_env/test.rs
index 1aeaf8be38..fd708290c4 100644
--- a/tooling/xtask/crates/xtask_local/src/local/local_env/test.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/local_env/test.rs
@@ -4,7 +4,7 @@ use crate::local::instance::{Instance, Port};
fn local_env() -> BTreeMap<String, String> {
let instance = Instance::derive(None, None).expect("default instance derives");
- LocalEnv::for_instance(Mode::Local, &instance).to_env()
+ LocalEnv::for_instance(Mode::Local, &instance, true).to_env()
}
/// Every key a local service relies on must be present — this is the test that
@@ -117,8 +117,8 @@ fn aws_creds_are_dummy() {
fn instance_secrets_are_scoped_but_identity_is_fixed() {
let default = Instance::derive(None, None).unwrap();
let agent_a = Instance::derive(Some("agent-a"), None).unwrap();
- let a = LocalEnv::for_instance(Mode::Local, &default).to_env();
- let b = LocalEnv::for_instance(Mode::Local, &agent_a).to_env();
+ let a = LocalEnv::for_instance(Mode::Local, &default, true).to_env();
+ let b = LocalEnv::for_instance(Mode::Local, &agent_a, true).to_env();
assert_ne!(
a.get("SERVICE_INTERNAL_AUTH_KEY"),
@@ -136,8 +136,8 @@ fn instance_secrets_are_scoped_but_identity_is_fixed() {
fn fusionauth_public_url_uses_the_instance_host_port() {
let default = Instance::derive(None, None).unwrap();
let named = Instance::derive(Some("2508"), None).unwrap();
- let default_env = LocalEnv::for_instance(Mode::Local, &default).to_env();
- let named_env = LocalEnv::for_instance(Mode::Local, &named).to_env();
+ let default_env = LocalEnv::for_instance(Mode::Local, &default, true).to_env();
+ let named_env = LocalEnv::for_instance(Mode::Local, &named, true).to_env();
let named_public_url = format!("http://localhost:{}", named.port(Port::FusionAuth));
assert_eq!(
diff --git a/tooling/xtask/crates/xtask_local/src/local/mod.rs b/tooling/xtask/crates/xtask_local/src/local/mod.rs
index d374b5ce62..27151fc67f 100644
--- a/tooling/xtask/crates/xtask_local/src/local/mod.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/mod.rs
@@ -475,6 +475,7 @@ fn prepare(
instance,
args.env.no_doppler,
args.env.env_file.as_deref(),
+ static_frontend,
)?;
stage.note(&format!("env: {}", env_layer::summarize(&env.merged)));
@@ -494,10 +495,15 @@ fn prepare(
// through the proxy in every mode), and — for the self-contained local
// stacks — the FusionAuth kickstart. (External networks/volumes are created
// by the caller after the background teardown joins.)
- gen_compose::generate(mode, instance, &binaries, static_frontend)?;
+ let gmail_forwarder = env
+ .merged
+ .get("GMAIL_FORWARDER_SA_KEY")
+ .is_some_and(|key| !key.trim().is_empty());
+ gen_compose::generate(mode, instance, &binaries, static_frontend, gmail_forwarder)?;
proxy::write_caddyfile(instance, mode, static_frontend)?;
if mode.spec().runs_local_infra {
- fusionauth::write_kickstart(instance)?;
+ let google = kickstart::GoogleIdp::from_env(&env.merged);
+ fusionauth::write_kickstart(instance, google.as_ref())?;
}
if args.build.build_aux_services {
build_aux_service_images(stage, instance, &env)?;
@@ -896,7 +902,7 @@ pub fn gen_compose_only(args: &cli::InstanceArgs) -> Result<()> {
let instance = Instance::derive(args.instance.as_deref(), args.port_base)?;
let target = arch::detect()?;
let binaries = build::BinariesDir::TargetDir(workspace_root().join(target.debug_dir()));
- let path = gen_compose::generate(Mode::Local, &instance, &binaries, false)?;
+ let path = gen_compose::generate(Mode::Local, &instance, &binaries, false, false)?;
println!("{}", path.display());
Ok(())
}
diff --git a/tooling/xtask/crates/xtask_local/src/local/proxy.rs b/tooling/xtask/crates/xtask_local/src/local/proxy.rs
index 062689a36a..3ea67b2eb1 100644
--- a/tooling/xtask/crates/xtask_local/src/local/proxy.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/proxy.rs
@@ -168,7 +168,7 @@ const STATIC_FILE_DEV: &str = r#" handle_path /static-file/* {
/// with `base: /app`, so URL space `/app/*` maps onto the dist root after the
/// prefix strip; unknown paths fall back to `index.html` (SPA routing). Caddy
/// sorts `redir` before `handle_path`, so the exact-path redirects win first.
-const FRONTEND_STATIC: &str = r#" redir / /app/ 302
+const FRONTEND_STATIC: &str = r#" redir / "/app/?{query}" 302
redir /app /app/ 308
handle_path /app/* {
root * /srv/frontend
diff --git a/tooling/xtask/crates/xtask_local/src/local/proxy/test.rs b/tooling/xtask/crates/xtask_local/src/local/proxy/test.rs
index 070ffce3e1..df6d20e0f5 100644
--- a/tooling/xtask/crates/xtask_local/src/local/proxy/test.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/proxy/test.rs
@@ -96,7 +96,7 @@ fn static_frontend_block_is_opt_in() {
assert!(headless.contains("handle_path /app/* {"));
assert!(headless.contains("root * /srv/frontend"));
assert!(headless.contains("try_files {path} /index.html"));
- assert!(headless.contains("redir / /app/ 302"));
+ assert!(headless.contains("redir / \"/app/?{query}\" 302"));
assert!(headless.contains("handle /mailpit/*"));
let attached = caddyfile(Mode::Local, false);
diff --git a/tooling/xtask/crates/xtask_local/src/local/resources.rs b/tooling/xtask/crates/xtask_local/src/local/resources.rs
index 28886a2aa2..f65b6796c1 100644
--- a/tooling/xtask/crates/xtask_local/src/local/resources.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/resources.rs
@@ -114,6 +114,15 @@ pub const QUEUES: &[Queue] = &[
name: macro_queues::EmailBackfillQueue::LOCAL,
bindings: &[("BACKFILL_QUEUE", Name), ("EMAIL_BACKFILL_QUEUE", Url)],
},
+ Queue {
+ // Consumed by email_service's nightly CRM-cleanup workers; without the
+ // queue existing in LocalStack they tight-loop on receive errors.
+ name: macro_queues::EmailCrmCleanupQueue::LOCAL,
+ bindings: &[(
+ macro_queues::EmailCrmCleanupQueue::OVERRIDE_ENV_VAR_NAME,
+ Url,
+ )],
+ },
Queue {
name: macro_queues::ChatDeleteQueue::LOCAL,
bindings: &[("CHAT_DELETE_QUEUE", Name)],
diff --git a/tooling/xtask/crates/xtask_local/src/local/snapshot/test.rs b/tooling/xtask/crates/xtask_local/src/local/snapshot/test.rs
index 38775c42dc..d70024ad7b 100644
--- a/tooling/xtask/crates/xtask_local/src/local/snapshot/test.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/snapshot/test.rs
@@ -8,7 +8,7 @@ use crate::local::instance::Instance;
#[test]
fn key_is_deterministic_and_kickstart_sensitive() {
let instance = Instance::derive(None, None).unwrap();
- crate::local::fusionauth::write_kickstart(&instance).unwrap();
+ crate::local::fusionauth::write_kickstart(&instance, None).unwrap();
let a = Plan::compute(&instance).unwrap();
let b = Plan::compute(&instance).unwrap();
@@ -17,7 +17,7 @@ fn key_is_deterministic_and_kickstart_sensitive() {
// A named instance generates a kickstart with different ports → new key.
let other = Instance::derive(Some("snapshot-key-test"), None).unwrap();
- crate::local::fusionauth::write_kickstart(&other).unwrap();
+ crate::local::fusionauth::write_kickstart(&other, None).unwrap();
let c = Plan::compute(&other).unwrap();
assert_ne!(
a.key, c.key,
diff --git a/tooling/xtask/crates/xtask_local/src/local/stack.rs b/tooling/xtask/crates/xtask_local/src/local/stack.rs
index f241ff95c5..edf3f9379c 100644
--- a/tooling/xtask/crates/xtask_local/src/local/stack.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/stack.rs
@@ -131,6 +131,13 @@ fn write_state(instance: &Instance, state: &StackState) -> Result<()> {
.with_context(|| format!("writing {}", path.display()))
}
+/// Whether the recorded stack serves the frontend as the static bundle on the
+/// proxy (headless `stack up`) rather than the dev server. False when no
+/// stack state exists (interactive `run_local`, which owns the dev server).
+pub(super) fn frontend_is_static(instance: &Instance) -> bool {
+ read_state(instance).is_some_and(|state| state.frontend == "static")
+}
+
fn read_state(instance: &Instance) -> Option<StackState> {
let raw = std::fs::read_to_string(state_path(instance)).ok()?;
serde_json::from_str(&raw).ok()
@@ -321,6 +328,7 @@ pub fn update(args: &UpdateArgs) -> Result<()> {
&instance,
args.env.no_doppler,
args.env.env_file.as_deref(),
+ state.frontend == "static",
)?;
let changed = if let Some(source) = args.binaries_dir.as_deref() {
let changed = apply_prebuilt_binaries(mode, &state, source)?;
@@ -550,8 +558,12 @@ pub fn down(args: &DownArgs) -> Result<()> {
pub fn snapshot_status(args: &SnapshotArgs) -> Result<()> {
let instance = Instance::derive(args.instance.instance.as_deref(), args.instance.port_base)?;
// The key hashes the generated kickstart; (re)write it so the verb works
- // before any `up` has run. Deterministic, so this never changes a key.
- super::fusionauth::write_kickstart(&instance)?;
+ // before any `up` has run. The kickstart depends on the resolved env (the
+ // optional Google IdP client), so resolve it the same way `up` does —
+ // otherwise the key reported here could differ from the key `up` computes.
+ let env = env_layer::resolve(Mode::Local, &instance, false, None, true)?;
+ let google = super::kickstart::GoogleIdp::from_env(&env.merged);
+ super::fusionauth::write_kickstart(&instance, google.as_ref())?;
let plan = snapshot::Plan::compute(&instance)?;
if args.json {
println!(
diff --git a/tooling/xtask/crates/xtask_local/src/local/summary.rs b/tooling/xtask/crates/xtask_local/src/local/summary.rs
index 43e638ae8b..902963913b 100644
--- a/tooling/xtask/crates/xtask_local/src/local/summary.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/summary.rs
@@ -11,12 +11,15 @@ use super::{Mode, frontend, mailpit, proxy};
/// The host-facing endpoints of an instance: (label, url, host port).
/// Shared by the startup summary and `status-local`.
pub fn endpoint_rows(instance: &Instance) -> Vec<(&'static str, String, u16)> {
+ // Headless stacks serve the app from the proxy origin; showing the
+ // dev-server URL there reads as "frontend down" when nothing is wrong.
+ let (frontend_url, frontend_port) = if super::stack::frontend_is_static(instance) {
+ (frontend::static_url(instance), instance.port(Port::Proxy))
+ } else {
+ (frontend::url(instance), instance.port(Port::Frontend))
+ };
vec![
- (
- "frontend",
- frontend::url(instance),
- instance.port(Port::Frontend),
- ),
+ ("frontend", frontend_url, frontend_port),
("proxy", proxy::url(instance), instance.port(Port::Proxy)),
(
"fusionauth",
diff --git a/tooling/xtask/crates/xtask_local/src/local/validate.rs b/tooling/xtask/crates/xtask_local/src/local/validate.rs
index fba7aad92a..db1cdfe976 100644
--- a/tooling/xtask/crates/xtask_local/src/local/validate.rs
+++ b/tooling/xtask/crates/xtask_local/src/local/validate.rs
@@ -8,6 +8,7 @@ use anyhow::{Context, Result, bail};
use serde_json::Value;
use super::build::{BinariesDir, RUNTIME_IMAGE_TAG};
+use super::instance::Port;
use super::inventory::services_for_mode;
use super::{Mode, arch, env_layer, gen_compose, instance::Instance, workspace_root};
@@ -24,14 +25,30 @@ const REQUIRED_NON_RUST: &[&str] = &[
/// Render the merged compose config and assert every Rust service is a
/// runtime-image container with no `build:` and an `/app/out` mount, and that
-/// the required non-Rust services exist.
+/// the required non-Rust services exist. Runs once per frontend flavor
+/// (static bundle vs dev server): the validator cannot know which one the
+/// developer will launch, so it must hold for both.
pub fn local_compose(instance: &Instance, mode: Mode) -> Result<()> {
+ for static_frontend in [true, false] {
+ local_compose_flavor(instance, mode, static_frontend)?;
+ }
+ Ok(())
+}
+
+fn local_compose_flavor(instance: &Instance, mode: Mode, static_frontend: bool) -> Result<()> {
// Generate the override against the expected (possibly not-yet-built)
// target dir — config rendering does not need the binaries to exist.
let target = arch::detect()?;
let binaries = BinariesDir::TargetDir(workspace_root().join(target.debug_dir()));
- gen_compose::generate(mode, instance, &binaries, false)?;
- let resolved = env_layer::resolve(mode, instance, true, None)?;
+ // Resolve first: the gmail_forwarder sidecar is gated on the resolved env
+ // exactly as `prepare` gates it, so the validated compose matches what a
+ // real bring-up with this env would generate.
+ let resolved = env_layer::resolve(mode, instance, true, None, static_frontend)?;
+ let gmail_forwarder = resolved
+ .merged
+ .get("GMAIL_FORWARDER_SA_KEY")
+ .is_some_and(|key| !key.trim().is_empty());
+ gen_compose::generate(mode, instance, &binaries, static_frontend, gmail_forwarder)?;
let files = gen_compose::compose_files(instance);
let mut cmd = gen_compose::docker_compose(instance, &files, &resolved.generated_path);
@@ -83,20 +100,48 @@ pub fn local_compose(instance: &Instance, mode: Mode) -> Result<()> {
failures.push(format!("required non-Rust service '{required}' is absent"));
}
}
+ // The sidecar is not in `services_for_mode` (modes-less inventory entry) —
+ // assert its presence and runtime-image shape when the env gates it in.
+ if gmail_forwarder {
+ match services.get("gmail_forwarder") {
+ None => failures.push(
+ "gmail_forwarder sidecar is absent although GMAIL_FORWARDER_SA_KEY is set".into(),
+ ),
+ Some(node) if !has_app_out_mount(node) => {
+ failures.push("gmail_forwarder is missing the /app/out bind mount".into());
+ }
+ Some(_) => {}
+ }
+ }
if !failures.is_empty() {
bail!(
- "validate-local-compose failed:\n - {}",
+ "validate-local-compose ({}) failed:\n - {}",
+ flavor_label(static_frontend),
failures.join("\n - ")
);
}
println!(
- "validate-local-compose: OK ({} Rust services)",
- services_for_mode(mode).count()
+ "validate-local-compose ({}): OK ({} Rust services{})",
+ flavor_label(static_frontend),
+ services_for_mode(mode).count(),
+ if gmail_forwarder {
+ " + gmail_forwarder"
+ } else {
+ ""
+ }
);
Ok(())
}
+fn flavor_label(static_frontend: bool) -> &'static str {
+ if static_frontend {
+ "static frontend"
+ } else {
+ "dev-server frontend"
+ }
+}
+
fn has_app_out_mount(service: &Value) -> bool {
let Some(volumes) = service.get("volumes").and_then(Value::as_array) else {
return false;
@@ -110,14 +155,29 @@ fn has_app_out_mount(service: &Value) -> bool {
})
}
-/// Resolve the env layers and assert mode-appropriate invariants.
+/// Resolve the env layers and assert mode-appropriate invariants, once per
+/// frontend flavor — the validator cannot know which one the developer will
+/// launch, so both must resolve to a sane configuration.
pub fn local_env(
instance: &Instance,
mode: Mode,
no_doppler: bool,
env_file: Option<&std::path::Path>,
) -> Result<()> {
- let resolved = env_layer::resolve(mode, instance, no_doppler, env_file)?;
+ for static_frontend in [true, false] {
+ local_env_flavor(instance, mode, no_doppler, env_file, static_frontend)?;
+ }
+ Ok(())
+}
+
+fn local_env_flavor(
+ instance: &Instance,
+ mode: Mode,
+ no_doppler: bool,
+ env_file: Option<&std::path::Path>,
+ static_frontend: bool,
+) -> Result<()> {
+ let resolved = env_layer::resolve(mode, instance, no_doppler, env_file, static_frontend)?;
let env = &resolved.merged;
let mut failures: Vec<String> = Vec::new();
@@ -163,6 +223,22 @@ pub fn local_env(
));
}
}
+ // The post-login redirect must point at where this flavor
+ // actually serves the app (proxy for static, dev server port
+ // otherwise) — the exact drift this per-flavor pass exists to
+ // catch.
+ let expected_frontend_port = if static_frontend {
+ instance.port(Port::Proxy)
+ } else {
+ instance.port(Port::Frontend)
+ };
+ if env.get("FRONTEND_PORT") != Some(&expected_frontend_port.to_string()) {
+ failures.push(format!(
+ "FRONTEND_PORT={:?} does not match the {} port {expected_frontend_port}",
+ env.get("FRONTEND_PORT"),
+ flavor_label(static_frontend),
+ ));
+ }
}
Mode::Dev => {
// run-dev runs as macro_env `local` *on purpose*: dev_personal ships
@@ -193,14 +269,16 @@ pub fn local_env(
if !failures.is_empty() {
bail!(
- "validate-local-env ({}) failed:\n - {}",
+ "validate-local-env ({}, {}) failed:\n - {}",
mode.label(),
+ flavor_label(static_frontend),
failures.join("\n - ")
);
}
println!(
- "validate-local-env ({}): OK — {}",
+ "validate-local-env ({}, {}): OK — {}",
mode.label(),
+ flavor_label(static_frontend),
env_layer::summarize(env)
);
Ok(())