From 94e019b4cffe123fcd25585475976282fbe479fc Mon Sep 17 00:00:00 2001 From: John Coffey Date: Fri, 13 Nov 2026 10:27:14 -0700 Subject: [PATCH] Add a Fastmail import source import fastmail imports from a Fastmail account over JMAP. It is import jmap with Fastmail's server (https://api.fastmail.com/jmap/session, where every Fastmail account reaches JMAP, custom domains included) and bearer-token sign-in already filled in, so it needs only an API token. What it brings across is whatever that account's session advertises: mail always, calendars and contacts where Fastmail offers them. The same import pipeline, so the estimate, the delta re-sync and the archive format all come with it. With no --account given it imports the account the session marks primary for mail, which a personal account has exactly one of; a new AccountSelector::Primary resolves that from the session's primaryAccounts (RFC 8620), falling back to the sole account and asking which only when there are several and none is primary. That spares the common case from naming its own account. --- CHANGELOG.md | 7 ++ README.md | 3 + docs/usage.md | 22 ++++++ src/cli.rs | 165 ++++++++++++++++++++++++++++++++++++++++ src/jmap/account.rs | 62 +++++++++++++++ src/jmap/session.rs | 5 ++ src/sync/import_jmap.rs | 3 +- 7 files changed, 266 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6d0cde3..0527f52 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ candidates before a series ships (`27.1-rc.1`). The tag is the version with a ## [Unreleased] +### Added +- `import fastmail` imports from a Fastmail account over JMAP. It is `import + jmap` with Fastmail's server and bearer-token sign-in filled in, so it needs + only an API token; with no `--account-*` it imports the account Fastmail + marks primary. Mail always; calendars and contacts where that account + advertises them. + ## [27.1-rc.13] The thirteenth release candidate of the 27.1 series: shell completions and a diff --git a/README.md b/README.md index e30c8de..14c7d16 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,9 @@ command reference is in [docs/usage.md](docs/usage.md). ## Sources - **JMAP** -- any JMAP account, including an inbuxa or Stalwart server. +- **Fastmail** -- JMAP, with its server and token filled in: just an API + token. Mail always; calendars and contacts where the account advertises + them. - **IMAP** -- mail only. Folders are chosen by name or by pattern. - **CalDAV, CardDAV** -- calendars and events, address books and contacts. - **WebDAV** -- a plain file collection, kept as a file tree. diff --git a/docs/usage.md b/docs/usage.md index 091afea..fe84273 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -111,6 +111,28 @@ The out-of-office reply, the server's `VacationResponse`, comes with and `type`, as inbuxa and other servers on the 0.16 line do, or `@type` and `mediaType`, as draft-ietf-jmap-filenode-18 servers such as Stalwart 1.0 do. +### Fastmail + +``` +inbuxa-migrate import fastmail \ + [--token [TOKEN]] \ + [--url ] \ + [--account-id | --account-name ] \ + [--objects ] \ + +``` + +The same as `import jmap`, with Fastmail's server +(`https://api.fastmail.com/jmap/session`) and bearer-token sign-in already +filled in, so it needs only a token. Create one in Fastmail at **Settings > +Privacy & Security > API tokens** with read access to Mail, Calendars and +Contacts; pass it with `--token`, in `$INBUXA_MIGRATE_API_KEY`, or at the +prompt. With no `--account-*` it imports the account Fastmail marks primary, +which is the one you want unless you have several. What crosses over is +whatever that account's session advertises: mail always, calendars and +contacts where Fastmail offers them over JMAP. `--url` overrides the server +for a Fastmail-compatible host. + ### IMAP ``` diff --git a/src/cli.rs b/src/cli.rs index 0ed97a9..994624d 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -129,6 +129,16 @@ enum Command { enum Source { #[command(about = "JMAP server")] Jmap(Box), + #[command( + about = "Fastmail (JMAP)", + name = "fastmail", + long_about = "Fastmail, over JMAP: a preset for `import jmap` already pointed at \ + Fastmail's server, so it needs only an API token. Create one in Fastmail at \ + Settings > Privacy & Security > API tokens, with read access to Mail, Calendars \ + and Contacts. What it brings across depends on what that account's JMAP session \ + offers: mail always, calendars and contacts where Fastmail advertises them." + )] + Fastmail(Box), #[command(about = "IMAP server")] Imap(Box), #[command(about = "CalDAV server")] @@ -286,6 +296,52 @@ struct JmapImportArgs { archive: PathBuf, } +#[derive(Args)] +struct FastmailImportArgs { + #[arg( + long, + value_name = "TOKEN", + num_args = 0..=1, + help = "Fastmail API token (value optional: falls back to $INBUXA_MIGRATE_API_KEY or a prompt)" + )] + token: Option>, + + #[arg( + long, + value_name = "URL", + help = "Override Fastmail's JMAP session URL (default: https://api.fastmail.com/jmap/session)" + )] + url: Option, + + #[arg(long, value_name = "ID", help = "Source account id")] + account_id: Option, + + #[arg(long, value_name = "NAME", help = "Source account name")] + account_name: Option, + + #[arg( + long, + value_name = "LIST", + help = "Comma-separated type list (default: all supported)" + )] + objects: Option, + + #[arg( + long, + help = "Permit importing when the archive records a different JMAP source" + )] + allow_source_change: bool, + + #[command(flatten)] + global: GlobalArgs, + + #[arg( + value_name = "ARCHIVE", + help = "Local SQLite archive (created if absent)" + )] + archive: PathBuf, +} + #[derive(Args)] #[command(group(clap::ArgGroup::new("auth").required(true).args(["auth_basic", "auth_bearer", "google_key", "google_key_from_env"])))] struct ImapImportArgs { @@ -1162,6 +1218,7 @@ impl Cli { fn resolve_import(source: Source) -> Result { match source { Source::Jmap(args) => resolve_jmap_import(*args), + Source::Fastmail(args) => resolve_fastmail_import(*args), Source::Imap(args) => resolve_imap_import(*args), Source::Caldav(args) => resolve_dav_import(*args, DavKindArg::Caldav), Source::Carddav(args) => resolve_dav_import(*args, DavKindArg::Carddav), @@ -1469,6 +1526,35 @@ fn resolve_jmap_import(args: JmapImportArgs) -> Result { )) } +/// Fastmail's JMAP session endpoint. Every Fastmail account reaches JMAP +/// through this host, custom domains included, so it is a fixed default. +const FASTMAIL_SESSION_URL: &str = "https://api.fastmail.com/jmap/session"; + +/// resolve_fastmail_import is resolve_jmap_import with Fastmail's server and +/// token filled in: the same JMAP import, so what it brings across is whatever +/// that account's session advertises. Fastmail's JMAP takes a bearer token +/// only, so there is no --auth-basic here. +fn resolve_fastmail_import(args: FastmailImportArgs) -> Result { + let common = common_config(&args.global, args.archive); + let auth = resolve_auth(None, None, args.token.as_ref(), None)?; + let account = resolve_account_or_primary(args.account_id, args.account_name)?; + let objects = args.objects.as_deref().map(parse_object_list).transpose()?; + + Ok(Action::Import( + common, + ImportConfig { + connect: ConnectConfig { + stay_on_url: false, + url: args.url.unwrap_or_else(|| FASTMAIL_SESSION_URL.to_owned()), + auth, + account, + }, + objects, + allow_source_change: args.allow_source_change, + }, + )) +} + fn resolve_imap_import(args: ImapImportArgs) -> Result { let common = common_config(&args.global, args.archive); let auth = match (&args.google_key, args.google_key_from_env) { @@ -2312,6 +2398,22 @@ fn resolve_account( } } +/// Like resolve_account, but neither given means the session's primary account +/// -- so a single-account import need not name it. +fn resolve_account_or_primary( + account_id: Option, + account_name: Option, +) -> Result { + match (account_id, account_name) { + (Some(id), None) => Ok(AccountSelector::Id(id)), + (None, Some(name)) => Ok(AccountSelector::Name(name)), + (None, None) => Ok(AccountSelector::Primary), + (Some(_), Some(_)) => Err(Error::Usage( + "give only one of --account-id / --account-name".to_owned(), + )), + } +} + #[cfg(test)] mod tests { use super::*; @@ -2347,6 +2449,69 @@ mod tests { assert!(matches!(cli.resolve().unwrap(), Action::Man)); } + #[test] + fn fastmail_defaults_to_fastmails_server_with_a_bearer_token() { + let cli = Cli::try_parse_from([ + "inbuxa-migrate", + "import", + "fastmail", + "--token", + "fmu-secret", + "archive.sqlite", + ]) + .unwrap_or_else(|e| panic!("clap rejected: {e}")); + match cli.resolve().unwrap() { + Action::Import(_, c) => { + assert_eq!(c.connect.url, "https://api.fastmail.com/jmap/session"); + assert!(!c.connect.stay_on_url); + assert!(matches!(c.connect.auth, Auth::Bearer { token } if token == "fmu-secret")); + // No --account given: default to the session's primary. + assert!(matches!(c.connect.account, AccountSelector::Primary)); + } + _ => panic!("expected Action::Import"), + } + } + + #[test] + fn fastmail_url_can_be_overridden() { + let cli = Cli::try_parse_from([ + "inbuxa-migrate", + "import", + "fastmail", + "--token", + "t", + "--url", + "https://api.messagingengine.com/jmap/session", + "archive.sqlite", + ]) + .unwrap_or_else(|e| panic!("clap rejected: {e}")); + match cli.resolve().unwrap() { + Action::Import(_, c) => { + assert_eq!( + c.connect.url, + "https://api.messagingengine.com/jmap/session" + ); + } + _ => panic!("expected Action::Import"), + } + } + + #[test] + fn fastmail_takes_no_basic_auth() { + // Fastmail's JMAP is bearer-only; --auth-basic is not a flag here. + assert!( + Cli::try_parse_from([ + "inbuxa-migrate", + "import", + "fastmail", + "--auth-basic", + "someone@fastmail.com", + "archive.sqlite", + ]) + .is_err() + ); + } + #[test] fn graph_max_rps_is_off_by_default_and_parsed_when_given() { assert_eq!(graph_config(&[]).unwrap().max_rps, None); diff --git a/src/jmap/account.rs b/src/jmap/account.rs index 8ec02d9..f6494f4 100644 --- a/src/jmap/account.rs +++ b/src/jmap/account.rs @@ -17,6 +17,9 @@ use std::fmt::Write; pub enum AccountSelector { Id(String), Name(String), + /// The account the session marks primary for mail, or the only one it + /// enumerates. Lets a single-account import run without naming it. + Primary, } const PRINCIPALS_URN: &str = "urn:ietf:params:jmap:principals"; @@ -36,6 +39,25 @@ pub fn resolve( } resolve_via_principal(name, session, client) } + AccountSelector::Primary => { + const MAIL_URN: &str = "urn:ietf:params:jmap:mail"; + if let Some(id) = session.primary_accounts.get(MAIL_URN) { + return Ok(id.clone()); + } + // No primary named: fall back to the only account, or ask which. + let mut ids = session.accounts.keys(); + match (ids.next(), ids.next()) { + (Some(id), None) => Ok(id.clone()), + (Some(_), Some(_)) => Err(Error::Account(format!( + "this session has {} accounts and names no primary for mail; \ + choose one with --account-name or --account-id", + session.accounts.len() + ))), + _ => Err(Error::Account( + "this session enumerates no account to import".to_owned(), + )), + } + } } } @@ -185,6 +207,46 @@ mod tests { ) } + #[test] + fn primary_selector_uses_primary_accounts() { + let raw = serde_json::json!({ + "apiUrl": "https://example.org/api", + "uploadUrl": "https://example.org/upload", + "downloadUrl": "https://example.org/download", + "capabilities": {}, + "accounts": { "a": { "name": "alice" }, "b": { "name": "bob" } }, + "primaryAccounts": { "urn:ietf:params:jmap:mail": "b" } + }); + let s: Session = serde_json::from_value(raw).unwrap(); + assert_eq!( + resolve(&AccountSelector::Primary, &s, &client()).unwrap(), + "b" + ); + } + + #[test] + fn primary_selector_falls_back_to_the_sole_account() { + // No primaryAccounts, but only one account: that is the one. + let s = session_with("alice@example.org", "only"); + assert_eq!( + resolve(&AccountSelector::Primary, &s, &client()).unwrap(), + "only" + ); + } + + #[test] + fn primary_selector_is_ambiguous_with_several_and_no_primary() { + let raw = serde_json::json!({ + "apiUrl": "https://example.org/api", + "uploadUrl": "https://example.org/upload", + "downloadUrl": "https://example.org/download", + "capabilities": {}, + "accounts": { "a": { "name": "alice" }, "b": { "name": "bob" } } + }); + let s: Session = serde_json::from_value(raw).unwrap(); + assert!(resolve(&AccountSelector::Primary, &s, &client()).is_err()); + } + #[test] fn id_selector_is_verbatim() { let s = session_with("alice", "a"); diff --git a/src/jmap/session.rs b/src/jmap/session.rs index 3ea159f..5d66fad 100644 --- a/src/jmap/session.rs +++ b/src/jmap/session.rs @@ -22,6 +22,11 @@ pub struct Session { pub download_url: String, pub capabilities: IndexMap, pub accounts: IndexMap, + /// The account the user treats as primary for each capability (RFC 8620), + /// which lets an import default to the right one without being told. Not + /// every server sends it, so it is optional. + #[serde(default)] + pub primary_accounts: IndexMap, } #[derive(Debug, Clone, Deserialize)] diff --git a/src/sync/import_jmap.rs b/src/sync/import_jmap.rs index abf434d..4d601a3 100644 --- a/src/sync/import_jmap.rs +++ b/src/sync/import_jmap.rs @@ -217,7 +217,8 @@ fn run_into( } else { let account_name = match &config.connect.account { crate::jmap::account::AccountSelector::Name(n) => Some(n.clone()), - crate::jmap::account::AccountSelector::Id(_) => None, + crate::jmap::account::AccountSelector::Id(_) + | crate::jmap::account::AccountSelector::Primary => None, }; Some( db::sources::upsert_source( -- 2.54.0