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(