@wtfalch/email 0.14.0 → 0.15.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +328 -8
- package/dist/imip/compose.d.ts +5 -0
- package/dist/imip/compose.js +84 -0
- package/dist/imip/index.d.ts +15 -0
- package/dist/imip/index.js +14 -0
- package/dist/imip/lookup.d.ts +21 -0
- package/dist/imip/lookup.js +26 -0
- package/dist/imip/parse.d.ts +11 -0
- package/dist/imip/parse.js +116 -0
- package/dist/imip/types.d.ts +57 -0
- package/dist/imip/types.js +9 -0
- package/dist/mailbox/client.d.ts +6 -0
- package/dist/mailbox/client.js +6 -0
- package/dist/mailbox/fake/mailbox.js +362 -2
- package/dist/mailbox/index.d.ts +6 -2
- package/dist/mailbox/index.js +3 -1
- package/dist/mailbox/sieve.d.ts +76 -0
- package/dist/mailbox/sieve.js +241 -0
- package/dist/mailbox/submit.d.ts +30 -2
- package/dist/mailbox/submit.js +57 -4
- package/dist/mailbox/types.d.ts +20 -0
- package/dist/mailbox/vacation.d.ts +32 -0
- package/dist/mailbox/vacation.js +79 -0
- package/dist/postmaster/index.d.ts +2 -0
- package/dist/postmaster/index.js +2 -0
- package/dist/postmaster/mail-copy.d.ts +169 -0
- package/dist/postmaster/mail-copy.js +259 -0
- package/dist/postmaster/org-mail.d.ts +117 -0
- package/dist/postmaster/org-mail.js +206 -0
- package/package.json +9 -4
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The exact Vandelay command lines foundry runs to copy one org's old mail
|
|
3
|
+
* from Google Workspace or Microsoft 365 into Stalwart
|
|
4
|
+
* (`wtfalch/email#108`), and nothing else: this module never spawns
|
|
5
|
+
* Vandelay, never touches a network, and never reads a real credential — it
|
|
6
|
+
* only decides argv.
|
|
7
|
+
*
|
|
8
|
+
* **Vandelay, not our own copier.** The user's choice, 2026-09-26: Stalwart
|
|
9
|
+
* ships `stalwartlabs/vandelay` (dual-licensed `Apache-2.0 OR MIT` — the
|
|
10
|
+
* SPDX header on every source file, e.g. `src/cli.rs:1-5`, and
|
|
11
|
+
* `LICENSES/Apache-2.0.txt`/`LICENSES/MIT.txt` at the repo root; commit
|
|
12
|
+
* `42f7c879115cd2179eff067f01ac14cdc4fad0ec`, `main` as of 2026-09-26), a
|
|
13
|
+
* JMAP importer-exporter that already speaks IMAP, JMAP, DAV, Exchange and
|
|
14
|
+
* Google Takeout. `import` reads a source account into a local SQLite
|
|
15
|
+
* archive; `export` pushes that archive into a target JMAP account — the
|
|
16
|
+
* two never talk to each other directly (vandelay `README.md:39`).
|
|
17
|
+
*
|
|
18
|
+
* **Both providers go through `import imap`, not a provider-specific
|
|
19
|
+
* importer.** Vandelay's IMAP importer authenticates with XOAUTH2
|
|
20
|
+
* (`--auth-bearer` + `--auth-user`, `src/cli.rs:206-219`) and imports "mail
|
|
21
|
+
* (and only mail)" (vandelay `README.md:167`) — exactly what this module
|
|
22
|
+
* needs, for either provider, with one argv shape. Microsoft also ships
|
|
23
|
+
* `import exchange-graph` (`src/cli.rs:1091-1284`), but it is one of the two
|
|
24
|
+
* importers the tool's own docs call experimental (vandelay `README.md:54-55`;
|
|
25
|
+
* stalw.art/docs/migration/import-export/import/exchange-graph/: "The
|
|
26
|
+
* Microsoft Exchange importers are experimental. The flag surface and
|
|
27
|
+
* behaviour may change between releases."), and its non-interactive path
|
|
28
|
+
* still needs an access token acquired *outside* Vandelay — `GraphAuth` is
|
|
29
|
+
* `PreAcquired` or an interactive `DeviceCode`, never a client-credentials
|
|
30
|
+
* flow Vandelay drives itself (`src/cli.rs:1262-1284`; contrast
|
|
31
|
+
* `exchange-ews`'s built-in `OAuthFlow::ClientCredentials`,
|
|
32
|
+
* `src/cli.rs:1066-1089`). Google's service-account flow and Microsoft's
|
|
33
|
+
* `IMAP.AccessAsApp` app-only flow (see the README's admin setup) both mint
|
|
34
|
+
* a bearer token before Vandelay ever runs either way, so Graph buys
|
|
35
|
+
* nothing by switching providers and costs a second, less-stable argv
|
|
36
|
+
* shape. Decision, 2026-09-26.
|
|
37
|
+
*
|
|
38
|
+
* **No secret ever lands in argv.** Every secret-bearing Vandelay flag
|
|
39
|
+
* (`--auth-password`, `--auth-bearer`, `--access-token`, `--ews-client-secret`)
|
|
40
|
+
* takes an *optional* inline value (`num_args = 0..=1` in `src/cli.rs`);
|
|
41
|
+
* passed bare, Vandelay resolves it from a same-named environment variable
|
|
42
|
+
* and finally an interactive, no-echo TTY prompt — never a file
|
|
43
|
+
* (`src/secret.rs:12-30`: flag value, then `$VAR`, then a TTY prompt, else a
|
|
44
|
+
* usage error naming the variable). Vandelay's own README recommends
|
|
45
|
+
* exactly this, never argv: "Credentials should be supplied via the ...
|
|
46
|
+
* environment variables, or via an interactive prompt; passing them on the
|
|
47
|
+
* command line is supported but not recommended" (`README.md:131`), and its
|
|
48
|
+
* quick start sets the variable and passes the flag bare (`README.md:92-109`).
|
|
49
|
+
* This module follows that: every `MailCopyEnv` names a variable and never
|
|
50
|
+
* carries a value, and every argv array this returns passes `--auth-bearer`
|
|
51
|
+
* with nothing after it.
|
|
52
|
+
*
|
|
53
|
+
* **The import token and the export token read the *same* variable name.**
|
|
54
|
+
* A bare `--auth-bearer` always resolves `$VANDELAY_TOKEN`, whether it is
|
|
55
|
+
* `import imap`'s source credential or `export`'s Stalwart credential
|
|
56
|
+
* (both resolved by the same `secret::resolve(bearer, "VANDELAY_TOKEN", ...)`
|
|
57
|
+
* call shape, `src/cli.rs:848` and `src/cli.rs:1322`) — Vandelay has no flag
|
|
58
|
+
* to pick a different variable name. Import and export are two separate
|
|
59
|
+
* process launches, never concurrent, so this is safe *only* if the caller
|
|
60
|
+
* sets `VANDELAY_TOKEN` to the source token for the import launch and to
|
|
61
|
+
* the Stalwart credential for the export launch, and never merges the two
|
|
62
|
+
* into one environment. `MailCopyAccountPlan.importEnv` and `.exportEnv`
|
|
63
|
+
* both name `VANDELAY_TOKEN` for exactly this reason: same name, two
|
|
64
|
+
* different moments, never both set at once.
|
|
65
|
+
*
|
|
66
|
+
* **Rerunning is safe.** Both commands are "convergent": import "picks up
|
|
67
|
+
* where it left off" on an interrupted run, or "pick[s] up new mail since
|
|
68
|
+
* the last snapshot" on a later one (vandelay `README.md:57,112`), matching
|
|
69
|
+
* blobs by BLAKE3 hash (`README.md:59`); export is "stateless re-matching
|
|
70
|
+
* on every run" and "upsert-only: matched items are updated, unmatched
|
|
71
|
+
* local items are created, but pre-existing target items not covered by the
|
|
72
|
+
* archive are left alone" (`README.md:56,277`) — a rerun never recopies or
|
|
73
|
+
* duplicates a message already on the Stalwart account. This module never
|
|
74
|
+
* sets `--prune`, so a plan built here can never delete anything on the
|
|
75
|
+
* target either.
|
|
76
|
+
*
|
|
77
|
+
* **Export targets a Stalwart account by id or name, with its own
|
|
78
|
+
* credential.** `--account-id`/`--account-name` (exactly one, `src/cli.rs:301`'s
|
|
79
|
+
* `ArgGroup`) names the target account; its auth (`--auth-basic`/`--auth-bearer`,
|
|
80
|
+
* same file, line 300) is separate from whatever authenticated the import.
|
|
81
|
+
* `./client.ts`'s own `StalwartClient` only accepts a Stalwart API key as
|
|
82
|
+
* `Authorization: Bearer` — never Basic, confirmed against a live instance
|
|
83
|
+
* (this package's README, "What it knows that the docs do not") — so
|
|
84
|
+
* export always uses `--auth-bearer` here, never `--auth-basic`.
|
|
85
|
+
*
|
|
86
|
+
* **Vandelay never checks that the export credential may write into that
|
|
87
|
+
* account — Stalwart does.** `--account-id`/`--account-name` is resolved
|
|
88
|
+
* verbatim and used as-is (`AccountSelector::Id(id) => Ok(id.clone())`,
|
|
89
|
+
* vandelay `src/jmap/account.rs:30`; `connect::prepare` then uses that id
|
|
90
|
+
* with no authorization check of its own, `src/jmap/connect.rs:39`). The
|
|
91
|
+
* gate is entirely server-side: Stalwart's request dispatcher requires
|
|
92
|
+
* `access_token.assert_has_access(account_id, Collection::Email)` for
|
|
93
|
+
* `Email/set` and the equivalent for `Mailbox/set`
|
|
94
|
+
* (`stalwartlabs/stalwart` `crates/jmap/src/api/request.rs:475,481` at
|
|
95
|
+
* commit `02503015580abd6706923d34e9d8e501e76f8634`), which
|
|
96
|
+
* `AccessToken::has_access` grants only when the credential either
|
|
97
|
+
* `is_member` of the target account — its own account, a group it belongs
|
|
98
|
+
* to, or holds the `impersonate` permission outright
|
|
99
|
+
* (`crates/common/src/auth/access_token.rs:476-480`) — or has been given
|
|
100
|
+
* ACL/shared access to that account's `Email` collection specifically
|
|
101
|
+
* (same file, lines 696-704). `impersonate` is already a name this
|
|
102
|
+
* package's own API keys can hold (see "What it knows that the docs do
|
|
103
|
+
* not", above), and is the practical choice for a migration credential
|
|
104
|
+
* that writes into many different accounts: mint the export key with
|
|
105
|
+
* `impersonate` rather than trying to pre-arrange per-account ACL shares.
|
|
106
|
+
*/
|
|
107
|
+
export type MailCopyProvider = 'google' | 'microsoft';
|
|
108
|
+
export declare class MailCopyPlanRefused extends Error {
|
|
109
|
+
}
|
|
110
|
+
export interface MailCopyAccount {
|
|
111
|
+
/** The mailbox to read at the source, e.g. `alice@acme.com`. Also the
|
|
112
|
+
* XOAUTH2 identity Vandelay's `--auth-user` sends. */
|
|
113
|
+
readonly source: string;
|
|
114
|
+
/** The Stalwart account this org's mail lands on. Exactly one of
|
|
115
|
+
* `targetAccountId`/`targetAccountName`, mirroring Vandelay's own
|
|
116
|
+
* `export` `ArgGroup` (`src/cli.rs:301`). */
|
|
117
|
+
readonly targetAccountId?: string;
|
|
118
|
+
readonly targetAccountName?: string;
|
|
119
|
+
}
|
|
120
|
+
export interface MailCopyOptions {
|
|
121
|
+
readonly provider: MailCopyProvider;
|
|
122
|
+
readonly accounts: readonly MailCopyAccount[];
|
|
123
|
+
/** The Stalwart JMAP base URL `export --url` writes to, e.g.
|
|
124
|
+
* `https://mail.wtfalch.dev`. */
|
|
125
|
+
readonly stalwartUrl: string;
|
|
126
|
+
/** Directory holding one Vandelay SQLite archive per account. */
|
|
127
|
+
readonly archiveDir: string;
|
|
128
|
+
}
|
|
129
|
+
/** An environment variable one Vandelay invocation needs — never its
|
|
130
|
+
* value. The caller sets it for that one subprocess launch. */
|
|
131
|
+
export interface MailCopyEnv {
|
|
132
|
+
readonly name: string;
|
|
133
|
+
readonly purpose: string;
|
|
134
|
+
}
|
|
135
|
+
export interface MailCopyAccountPlan {
|
|
136
|
+
readonly source: string;
|
|
137
|
+
/** The local SQLite archive this account's import fills and its export
|
|
138
|
+
* reads back. */
|
|
139
|
+
readonly archive: string;
|
|
140
|
+
readonly importArgv: readonly string[];
|
|
141
|
+
readonly importEnv: readonly MailCopyEnv[];
|
|
142
|
+
readonly exportArgv: readonly string[];
|
|
143
|
+
readonly exportEnv: readonly MailCopyEnv[];
|
|
144
|
+
}
|
|
145
|
+
export interface MailCopyPlan {
|
|
146
|
+
readonly provider: MailCopyProvider;
|
|
147
|
+
readonly accounts: readonly MailCopyAccountPlan[];
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* The Vandelay commands foundry runs to copy every account of one org's old
|
|
151
|
+
* mail from `input.provider` into Stalwart: one `import imap` and one
|
|
152
|
+
* `export` per account, plus the environment variable names (never values)
|
|
153
|
+
* each needs. Pure and idempotent — calling this twice with the same input
|
|
154
|
+
* returns the same plan, and running the returned commands twice against
|
|
155
|
+
* the same archive and account is exactly the rerun Vandelay is built to
|
|
156
|
+
* support (see this file's module doc comment).
|
|
157
|
+
*
|
|
158
|
+
* Refuses before building anything: a `stalwartUrl` that is not https (a
|
|
159
|
+
* bearer credential over http is the credential in clear, the same rule
|
|
160
|
+
* `openInstance` applies in `./instance.ts`), a `stalwartUrl` carrying
|
|
161
|
+
* embedded userinfo (`https://user:secret@host/`, which would put that
|
|
162
|
+
* secret straight into `exportArgv`), an empty `archiveDir`, no accounts, an
|
|
163
|
+
* account whose `source` is not email-shaped, an account that names both or
|
|
164
|
+
* neither of `targetAccountId`/`targetAccountName`, or two accounts that
|
|
165
|
+
* would land on the same archive file (see `archiveFileName`) — always a
|
|
166
|
+
* mistake, since it means one account's mail would import into the other's
|
|
167
|
+
* archive.
|
|
168
|
+
*/
|
|
169
|
+
export declare function mailCopyPlan(input: MailCopyOptions): MailCopyPlan;
|
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The exact Vandelay command lines foundry runs to copy one org's old mail
|
|
3
|
+
* from Google Workspace or Microsoft 365 into Stalwart
|
|
4
|
+
* (`wtfalch/email#108`), and nothing else: this module never spawns
|
|
5
|
+
* Vandelay, never touches a network, and never reads a real credential — it
|
|
6
|
+
* only decides argv.
|
|
7
|
+
*
|
|
8
|
+
* **Vandelay, not our own copier.** The user's choice, 2026-09-26: Stalwart
|
|
9
|
+
* ships `stalwartlabs/vandelay` (dual-licensed `Apache-2.0 OR MIT` — the
|
|
10
|
+
* SPDX header on every source file, e.g. `src/cli.rs:1-5`, and
|
|
11
|
+
* `LICENSES/Apache-2.0.txt`/`LICENSES/MIT.txt` at the repo root; commit
|
|
12
|
+
* `42f7c879115cd2179eff067f01ac14cdc4fad0ec`, `main` as of 2026-09-26), a
|
|
13
|
+
* JMAP importer-exporter that already speaks IMAP, JMAP, DAV, Exchange and
|
|
14
|
+
* Google Takeout. `import` reads a source account into a local SQLite
|
|
15
|
+
* archive; `export` pushes that archive into a target JMAP account — the
|
|
16
|
+
* two never talk to each other directly (vandelay `README.md:39`).
|
|
17
|
+
*
|
|
18
|
+
* **Both providers go through `import imap`, not a provider-specific
|
|
19
|
+
* importer.** Vandelay's IMAP importer authenticates with XOAUTH2
|
|
20
|
+
* (`--auth-bearer` + `--auth-user`, `src/cli.rs:206-219`) and imports "mail
|
|
21
|
+
* (and only mail)" (vandelay `README.md:167`) — exactly what this module
|
|
22
|
+
* needs, for either provider, with one argv shape. Microsoft also ships
|
|
23
|
+
* `import exchange-graph` (`src/cli.rs:1091-1284`), but it is one of the two
|
|
24
|
+
* importers the tool's own docs call experimental (vandelay `README.md:54-55`;
|
|
25
|
+
* stalw.art/docs/migration/import-export/import/exchange-graph/: "The
|
|
26
|
+
* Microsoft Exchange importers are experimental. The flag surface and
|
|
27
|
+
* behaviour may change between releases."), and its non-interactive path
|
|
28
|
+
* still needs an access token acquired *outside* Vandelay — `GraphAuth` is
|
|
29
|
+
* `PreAcquired` or an interactive `DeviceCode`, never a client-credentials
|
|
30
|
+
* flow Vandelay drives itself (`src/cli.rs:1262-1284`; contrast
|
|
31
|
+
* `exchange-ews`'s built-in `OAuthFlow::ClientCredentials`,
|
|
32
|
+
* `src/cli.rs:1066-1089`). Google's service-account flow and Microsoft's
|
|
33
|
+
* `IMAP.AccessAsApp` app-only flow (see the README's admin setup) both mint
|
|
34
|
+
* a bearer token before Vandelay ever runs either way, so Graph buys
|
|
35
|
+
* nothing by switching providers and costs a second, less-stable argv
|
|
36
|
+
* shape. Decision, 2026-09-26.
|
|
37
|
+
*
|
|
38
|
+
* **No secret ever lands in argv.** Every secret-bearing Vandelay flag
|
|
39
|
+
* (`--auth-password`, `--auth-bearer`, `--access-token`, `--ews-client-secret`)
|
|
40
|
+
* takes an *optional* inline value (`num_args = 0..=1` in `src/cli.rs`);
|
|
41
|
+
* passed bare, Vandelay resolves it from a same-named environment variable
|
|
42
|
+
* and finally an interactive, no-echo TTY prompt — never a file
|
|
43
|
+
* (`src/secret.rs:12-30`: flag value, then `$VAR`, then a TTY prompt, else a
|
|
44
|
+
* usage error naming the variable). Vandelay's own README recommends
|
|
45
|
+
* exactly this, never argv: "Credentials should be supplied via the ...
|
|
46
|
+
* environment variables, or via an interactive prompt; passing them on the
|
|
47
|
+
* command line is supported but not recommended" (`README.md:131`), and its
|
|
48
|
+
* quick start sets the variable and passes the flag bare (`README.md:92-109`).
|
|
49
|
+
* This module follows that: every `MailCopyEnv` names a variable and never
|
|
50
|
+
* carries a value, and every argv array this returns passes `--auth-bearer`
|
|
51
|
+
* with nothing after it.
|
|
52
|
+
*
|
|
53
|
+
* **The import token and the export token read the *same* variable name.**
|
|
54
|
+
* A bare `--auth-bearer` always resolves `$VANDELAY_TOKEN`, whether it is
|
|
55
|
+
* `import imap`'s source credential or `export`'s Stalwart credential
|
|
56
|
+
* (both resolved by the same `secret::resolve(bearer, "VANDELAY_TOKEN", ...)`
|
|
57
|
+
* call shape, `src/cli.rs:848` and `src/cli.rs:1322`) — Vandelay has no flag
|
|
58
|
+
* to pick a different variable name. Import and export are two separate
|
|
59
|
+
* process launches, never concurrent, so this is safe *only* if the caller
|
|
60
|
+
* sets `VANDELAY_TOKEN` to the source token for the import launch and to
|
|
61
|
+
* the Stalwart credential for the export launch, and never merges the two
|
|
62
|
+
* into one environment. `MailCopyAccountPlan.importEnv` and `.exportEnv`
|
|
63
|
+
* both name `VANDELAY_TOKEN` for exactly this reason: same name, two
|
|
64
|
+
* different moments, never both set at once.
|
|
65
|
+
*
|
|
66
|
+
* **Rerunning is safe.** Both commands are "convergent": import "picks up
|
|
67
|
+
* where it left off" on an interrupted run, or "pick[s] up new mail since
|
|
68
|
+
* the last snapshot" on a later one (vandelay `README.md:57,112`), matching
|
|
69
|
+
* blobs by BLAKE3 hash (`README.md:59`); export is "stateless re-matching
|
|
70
|
+
* on every run" and "upsert-only: matched items are updated, unmatched
|
|
71
|
+
* local items are created, but pre-existing target items not covered by the
|
|
72
|
+
* archive are left alone" (`README.md:56,277`) — a rerun never recopies or
|
|
73
|
+
* duplicates a message already on the Stalwart account. This module never
|
|
74
|
+
* sets `--prune`, so a plan built here can never delete anything on the
|
|
75
|
+
* target either.
|
|
76
|
+
*
|
|
77
|
+
* **Export targets a Stalwart account by id or name, with its own
|
|
78
|
+
* credential.** `--account-id`/`--account-name` (exactly one, `src/cli.rs:301`'s
|
|
79
|
+
* `ArgGroup`) names the target account; its auth (`--auth-basic`/`--auth-bearer`,
|
|
80
|
+
* same file, line 300) is separate from whatever authenticated the import.
|
|
81
|
+
* `./client.ts`'s own `StalwartClient` only accepts a Stalwart API key as
|
|
82
|
+
* `Authorization: Bearer` — never Basic, confirmed against a live instance
|
|
83
|
+
* (this package's README, "What it knows that the docs do not") — so
|
|
84
|
+
* export always uses `--auth-bearer` here, never `--auth-basic`.
|
|
85
|
+
*
|
|
86
|
+
* **Vandelay never checks that the export credential may write into that
|
|
87
|
+
* account — Stalwart does.** `--account-id`/`--account-name` is resolved
|
|
88
|
+
* verbatim and used as-is (`AccountSelector::Id(id) => Ok(id.clone())`,
|
|
89
|
+
* vandelay `src/jmap/account.rs:30`; `connect::prepare` then uses that id
|
|
90
|
+
* with no authorization check of its own, `src/jmap/connect.rs:39`). The
|
|
91
|
+
* gate is entirely server-side: Stalwart's request dispatcher requires
|
|
92
|
+
* `access_token.assert_has_access(account_id, Collection::Email)` for
|
|
93
|
+
* `Email/set` and the equivalent for `Mailbox/set`
|
|
94
|
+
* (`stalwartlabs/stalwart` `crates/jmap/src/api/request.rs:475,481` at
|
|
95
|
+
* commit `02503015580abd6706923d34e9d8e501e76f8634`), which
|
|
96
|
+
* `AccessToken::has_access` grants only when the credential either
|
|
97
|
+
* `is_member` of the target account — its own account, a group it belongs
|
|
98
|
+
* to, or holds the `impersonate` permission outright
|
|
99
|
+
* (`crates/common/src/auth/access_token.rs:476-480`) — or has been given
|
|
100
|
+
* ACL/shared access to that account's `Email` collection specifically
|
|
101
|
+
* (same file, lines 696-704). `impersonate` is already a name this
|
|
102
|
+
* package's own API keys can hold (see "What it knows that the docs do
|
|
103
|
+
* not", above), and is the practical choice for a migration credential
|
|
104
|
+
* that writes into many different accounts: mint the export key with
|
|
105
|
+
* `impersonate` rather than trying to pre-arrange per-account ACL shares.
|
|
106
|
+
*/
|
|
107
|
+
/**
|
|
108
|
+
* The IMAP host Vandelay's `--url` targets, confirmed live on each
|
|
109
|
+
* provider's own settings page: `imap.gmail.com:993`
|
|
110
|
+
* (developers.google.com/workspace/gmail/imap/imap-smtp: "Incoming
|
|
111
|
+
* connections to the IMAP server at imap.gmail.com:993") and
|
|
112
|
+
* `outlook.office365.com:993`
|
|
113
|
+
* (support.microsoft.com/article/pop-and-imap-email-settings-for-outlook-8361e398-8af4-4e97-b147-6c6c4ac95353).
|
|
114
|
+
*/
|
|
115
|
+
const IMAP_URL = {
|
|
116
|
+
google: 'imaps://imap.gmail.com',
|
|
117
|
+
microsoft: 'imaps://outlook.office365.com',
|
|
118
|
+
};
|
|
119
|
+
/** The env var name every bare `--auth-bearer` resolves (`src/secret.rs:12-30`).
|
|
120
|
+
* Named once so the import and export sides are visibly the same
|
|
121
|
+
* variable, not two names that happen to collide. */
|
|
122
|
+
const VANDELAY_TOKEN = 'VANDELAY_TOKEN';
|
|
123
|
+
export class MailCopyPlanRefused extends Error {
|
|
124
|
+
}
|
|
125
|
+
/** A very small email shape check: exactly one `@`, something on both
|
|
126
|
+
* sides. Vandelay and both providers accept far more than this; the point
|
|
127
|
+
* here is only to refuse an empty string or a pasted display name before
|
|
128
|
+
* it becomes an XOAUTH2 identity. */
|
|
129
|
+
function assertEmailish(value) {
|
|
130
|
+
const at = value.indexOf('@');
|
|
131
|
+
if (at <= 0 || at === value.length - 1 || value.indexOf('@', at + 1) !== -1) {
|
|
132
|
+
throw new MailCopyPlanRefused(`"${value}" does not look like an email address`);
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* A filesystem-safe archive filename derived only from the account's
|
|
137
|
+
* address, never from anything time-based — so two calls with the same
|
|
138
|
+
* input produce the same path, which is what makes a rerun's plan
|
|
139
|
+
* idempotent.
|
|
140
|
+
*
|
|
141
|
+
* `encodeURIComponent` rather than a hand-rolled collapse of "unsafe"
|
|
142
|
+
* characters to `_`: two different addresses must never fold onto the same
|
|
143
|
+
* file, or their mail crosses between accounts. A collapse is not
|
|
144
|
+
* injective — `alice+bob@acme.com` and `alice_bob@acme.com` both
|
|
145
|
+
* flattened to `alice_bob_at_acme.com` — while percent-encoding only ever
|
|
146
|
+
* rewrites a character to a fixed, distinct token (`+` to `%2B`, `@` to
|
|
147
|
+
* `%40`, …) and leaves `_` alone, so no two distinct inputs can collide
|
|
148
|
+
* through this function alone. `mailCopyPlan` still checks the *result*
|
|
149
|
+
* for collisions across a whole plan (case-folding two spellings of one
|
|
150
|
+
* mailbox together, for instance), since that is a real answer, not a bug
|
|
151
|
+
* in the encoding.
|
|
152
|
+
*/
|
|
153
|
+
function archiveFileName(source) {
|
|
154
|
+
return `${encodeURIComponent(source.toLowerCase())}.sqlite`;
|
|
155
|
+
}
|
|
156
|
+
/** `--account-id=<id>` or `--account-name=<name>`, refusing both or
|
|
157
|
+
* neither rather than silently preferring one — the same exactly-one rule
|
|
158
|
+
* Vandelay's own `export` enforces with an `ArgGroup` (`src/cli.rs:301`).
|
|
159
|
+
* The `=` form, rather than two argv elements, so a value starting with
|
|
160
|
+
* `-` (an id or name clap would otherwise mistake for another flag) still
|
|
161
|
+
* parses as this flag's value. */
|
|
162
|
+
function accountSelectorArgv(account) {
|
|
163
|
+
const { targetAccountId, targetAccountName } = account;
|
|
164
|
+
if (targetAccountId && targetAccountName) {
|
|
165
|
+
throw new MailCopyPlanRefused(`${account.source} names both a target account id and a target account name; export takes exactly one`);
|
|
166
|
+
}
|
|
167
|
+
if (targetAccountId)
|
|
168
|
+
return `--account-id=${targetAccountId}`;
|
|
169
|
+
if (targetAccountName)
|
|
170
|
+
return `--account-name=${targetAccountName}`;
|
|
171
|
+
throw new MailCopyPlanRefused(`${account.source} needs a target Stalwart account id or name`);
|
|
172
|
+
}
|
|
173
|
+
function planAccount(account, imapUrl, stalwartUrl, archiveDir) {
|
|
174
|
+
assertEmailish(account.source);
|
|
175
|
+
const accountFlag = accountSelectorArgv(account);
|
|
176
|
+
const archive = `${archiveDir}/${archiveFileName(account.source)}`;
|
|
177
|
+
// `--` before the positional archive path: without it, an archiveDir
|
|
178
|
+
// starting with `-` would parse as an unrecognised flag rather than the
|
|
179
|
+
// ARCHIVE positional (clap does not special-case a leading `-` on a
|
|
180
|
+
// positional). Harmless, and always included, when it does not.
|
|
181
|
+
const importArgv = [
|
|
182
|
+
'import',
|
|
183
|
+
'imap',
|
|
184
|
+
'--url',
|
|
185
|
+
imapUrl,
|
|
186
|
+
'--auth-bearer',
|
|
187
|
+
`--auth-user=${account.source}`,
|
|
188
|
+
'--',
|
|
189
|
+
archive,
|
|
190
|
+
];
|
|
191
|
+
const importEnv = [
|
|
192
|
+
{ name: VANDELAY_TOKEN, purpose: `the source XOAUTH2 bearer token for ${account.source}` },
|
|
193
|
+
];
|
|
194
|
+
const exportArgv = ['export', '--url', stalwartUrl, '--auth-bearer', accountFlag, '--', archive];
|
|
195
|
+
const exportEnv = [
|
|
196
|
+
{
|
|
197
|
+
name: VANDELAY_TOKEN,
|
|
198
|
+
purpose: `the Stalwart account credential for ${account.source}'s target account`,
|
|
199
|
+
},
|
|
200
|
+
];
|
|
201
|
+
return { source: account.source, archive, importArgv, importEnv, exportArgv, exportEnv };
|
|
202
|
+
}
|
|
203
|
+
/**
|
|
204
|
+
* The Vandelay commands foundry runs to copy every account of one org's old
|
|
205
|
+
* mail from `input.provider` into Stalwart: one `import imap` and one
|
|
206
|
+
* `export` per account, plus the environment variable names (never values)
|
|
207
|
+
* each needs. Pure and idempotent — calling this twice with the same input
|
|
208
|
+
* returns the same plan, and running the returned commands twice against
|
|
209
|
+
* the same archive and account is exactly the rerun Vandelay is built to
|
|
210
|
+
* support (see this file's module doc comment).
|
|
211
|
+
*
|
|
212
|
+
* Refuses before building anything: a `stalwartUrl` that is not https (a
|
|
213
|
+
* bearer credential over http is the credential in clear, the same rule
|
|
214
|
+
* `openInstance` applies in `./instance.ts`), a `stalwartUrl` carrying
|
|
215
|
+
* embedded userinfo (`https://user:secret@host/`, which would put that
|
|
216
|
+
* secret straight into `exportArgv`), an empty `archiveDir`, no accounts, an
|
|
217
|
+
* account whose `source` is not email-shaped, an account that names both or
|
|
218
|
+
* neither of `targetAccountId`/`targetAccountName`, or two accounts that
|
|
219
|
+
* would land on the same archive file (see `archiveFileName`) — always a
|
|
220
|
+
* mistake, since it means one account's mail would import into the other's
|
|
221
|
+
* archive.
|
|
222
|
+
*/
|
|
223
|
+
export function mailCopyPlan(input) {
|
|
224
|
+
if (input.provider !== 'google' && input.provider !== 'microsoft') {
|
|
225
|
+
throw new MailCopyPlanRefused(`provider must be "google" or "microsoft", got "${String(input.provider)}"`);
|
|
226
|
+
}
|
|
227
|
+
const stalwartUrl = input.stalwartUrl.trim().replace(/\/+$/, '');
|
|
228
|
+
if (!/^https:\/\//.test(stalwartUrl)) {
|
|
229
|
+
throw new MailCopyPlanRefused(`the Stalwart URL must be https, got "${input.stalwartUrl}"`);
|
|
230
|
+
}
|
|
231
|
+
let parsedUrl;
|
|
232
|
+
try {
|
|
233
|
+
parsedUrl = new URL(stalwartUrl);
|
|
234
|
+
}
|
|
235
|
+
catch {
|
|
236
|
+
throw new MailCopyPlanRefused(`"${input.stalwartUrl}" is not a valid URL`);
|
|
237
|
+
}
|
|
238
|
+
if (parsedUrl.username || parsedUrl.password) {
|
|
239
|
+
throw new MailCopyPlanRefused('the Stalwart URL must not carry embedded credentials; use --auth-bearer instead');
|
|
240
|
+
}
|
|
241
|
+
const archiveDir = input.archiveDir.trim().replace(/\/+$/, '');
|
|
242
|
+
if (!archiveDir) {
|
|
243
|
+
throw new MailCopyPlanRefused('an archive directory is required');
|
|
244
|
+
}
|
|
245
|
+
if (input.accounts.length === 0) {
|
|
246
|
+
throw new MailCopyPlanRefused('at least one account is required');
|
|
247
|
+
}
|
|
248
|
+
const imapUrl = IMAP_URL[input.provider];
|
|
249
|
+
const accounts = input.accounts.map((account) => planAccount(account, imapUrl, stalwartUrl, archiveDir));
|
|
250
|
+
const seenArchives = new Map();
|
|
251
|
+
for (const account of accounts) {
|
|
252
|
+
const collidesWith = seenArchives.get(account.archive);
|
|
253
|
+
if (collidesWith) {
|
|
254
|
+
throw new MailCopyPlanRefused(`${account.source} and ${collidesWith} would both use the archive "${account.archive}"; give them distinct addresses or split the plan`);
|
|
255
|
+
}
|
|
256
|
+
seenArchives.set(account.archive, account.source);
|
|
257
|
+
}
|
|
258
|
+
return { provider: input.provider, accounts };
|
|
259
|
+
}
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import type { StalwartClient } from './client.js';
|
|
2
|
+
/**
|
|
3
|
+
* One org's mail on the one shared Stalwart server (foundry issue #7,
|
|
4
|
+
* `wtfalch/email#96`): give it a `Domain`, change its mode, or park it —
|
|
5
|
+
* never a second Stalwart, never a per-org instance.
|
|
6
|
+
*
|
|
7
|
+
* **What this does and does not touch.** The shared instance itself —
|
|
8
|
+
* `AcmeProvider`, `DnsServer`, the Resend relay, `SystemSettings` — is
|
|
9
|
+
* provisioned once, by `mailObjects`/`applyObjects` in `./objects.ts`. This
|
|
10
|
+
* module only upserts the one `Domain` object an org needs on top of that,
|
|
11
|
+
* confirmed against `stalwartlabs/stalwart` at commit
|
|
12
|
+
* `02503015580abd6706923d34e9d8e501e76f8634`:
|
|
13
|
+
* `crates/registry/src/schema/structs.rs:2696-2731` is `struct Domain`, whose
|
|
14
|
+
* `isEnabled` (line 2703-2704, `#[serde(rename = "isEnabled")] pub is_enabled:
|
|
15
|
+
* bool`) is the one field `parkOrgMail` writes, and whose
|
|
16
|
+
* `certificateManagement`/`dnsManagement`/`dkimManagement` (lines 2711-2716)
|
|
17
|
+
* are the same three `@type`-tagged blocks `mailObjects` already writes on
|
|
18
|
+
* the instance-level `Domain` object.
|
|
19
|
+
*
|
|
20
|
+
* **`certificateManagement` and `dnsManagement` are `Manual` here on
|
|
21
|
+
* purpose.** `Automatic` on either would have Stalwart call Cloudflare
|
|
22
|
+
* itself (`DnsManagementProperties.dns_server_id`, same file, lines
|
|
23
|
+
* 1311-1320) — but the campaign ledger's non-goals say foundry owns
|
|
24
|
+
* Cloudflare, so this API only *returns* the records foundry must publish
|
|
25
|
+
* and never calls a DNS provider. `dkimManagement` stays `Automatic`
|
|
26
|
+
* (`DkimManagement::Automatic`, lines 998-1016): Stalwart still mints and
|
|
27
|
+
* rotates the signing key itself, on its own background task
|
|
28
|
+
* (`crates/jmap/src/registry/mapping/domain.rs:102-133`, `will_trigger_dkim`
|
|
29
|
+
* queues `Task::DkimManagement` whenever a domain's `dkimManagement` becomes
|
|
30
|
+
* `Automatic`) — this module only reads the key back.
|
|
31
|
+
*
|
|
32
|
+
* **The management API can read back what a domain needs published**,
|
|
33
|
+
* settling the one open question task B step 1 was for. `x:Domain/get`
|
|
34
|
+
* computes an extra `dnsZoneFile` property whenever the caller's
|
|
35
|
+
* `properties` list is empty or names it —
|
|
36
|
+
* `crates/jmap/src/registry/get.rs:297-304` — by calling
|
|
37
|
+
* `Server::build_bind_dns_records` (`crates/common/src/network/dns/records.rs:357-382`),
|
|
38
|
+
* which serializes DKIM, MX, SPF, DMARC, TLS-RPT, CAA and more as a BIND
|
|
39
|
+
* zone file (`stalwartlabs/dns-update`'s `BindSerializer::serialize`,
|
|
40
|
+
* `src/bind.rs:17-78` at commit `40e94d85bdbdeeb3a13d4ac8e84a33de5baa6b49`).
|
|
41
|
+
* `StalwartClient.get` already sends no `properties` argument, so the
|
|
42
|
+
* `dnsZoneFile` text comes back on every plain `Domain` read for free.
|
|
43
|
+
*
|
|
44
|
+
* Only the `_domainkey` lines are worth reading back, because MX and SPF are
|
|
45
|
+
* fully derivable from `apex`/`mailHost` without a round trip — this is the
|
|
46
|
+
* "return the records you can derive" fallback the task brief names, applied
|
|
47
|
+
* unconditionally rather than only when the read fails. DKIM's record name
|
|
48
|
+
* (`<selector>._domainkey.<domain>.`) and value (`v=DKIM1; k=rsa; h=sha256;
|
|
49
|
+
* p=<base64>`) come from `generate_dkim_dns_record`,
|
|
50
|
+
* `crates/common/src/network/dkim.rs:116-149`, same commit as the schema.
|
|
51
|
+
*
|
|
52
|
+
* **The DKIM record can be empty right after the first `applyOrgMail`.**
|
|
53
|
+
* `Task::DkimManagement` runs after the `Domain/set` that queued it, not
|
|
54
|
+
* inside it, and `build_dns_records`'s `Dkim` arm skips any signature that
|
|
55
|
+
* is not yet `is_published()` (`records.rs:41-58`). A caller that needs the
|
|
56
|
+
* key immediately should call `applyOrgMail` again a moment later — it is
|
|
57
|
+
* idempotent, so a repeat costs nothing beyond the read.
|
|
58
|
+
*/
|
|
59
|
+
export type OrgMailMode = 'received' | 'hosted';
|
|
60
|
+
export interface OrgMailOrg {
|
|
61
|
+
readonly slug: string;
|
|
62
|
+
/** Absent for a level-1 org: its domain is `${slug}.${apex}` and its mode must be `hosted`. */
|
|
63
|
+
readonly domain?: string;
|
|
64
|
+
readonly mode: OrgMailMode;
|
|
65
|
+
}
|
|
66
|
+
export interface OrgMailOptions {
|
|
67
|
+
/** The shared mail apex a level-1 org's domain is built under, e.g. `oikos.host`. */
|
|
68
|
+
readonly apex: string;
|
|
69
|
+
/** The MX target and TLS name every domain on this instance shares, e.g. `mail.oikos.host`. */
|
|
70
|
+
readonly mailHost: string;
|
|
71
|
+
}
|
|
72
|
+
/** One DNS record foundry must publish. `priority` is set only for `MX`. */
|
|
73
|
+
export interface DnsRecordSpec {
|
|
74
|
+
readonly type: 'MX' | 'TXT';
|
|
75
|
+
/** Fully-qualified, no trailing dot — e.g. `acme.oikos.host` or `selector1._domainkey.acme.oikos.host`. */
|
|
76
|
+
readonly name: string;
|
|
77
|
+
readonly value: string;
|
|
78
|
+
readonly priority?: number;
|
|
79
|
+
}
|
|
80
|
+
export interface OrgMailResult {
|
|
81
|
+
readonly domain: string;
|
|
82
|
+
readonly records: readonly DnsRecordSpec[];
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* The `_domainkey` TXT records inside a `dnsZoneFile` BIND zone, as
|
|
86
|
+
* `x:Domain/get` returns it. Every other record type in the zone (MX, SPF,
|
|
87
|
+
* DMARC, TLS-RPT, CAA, autoconfig, …) is derived instead of read back, so
|
|
88
|
+
* this reads only the lines whose name contains `._domainkey.`.
|
|
89
|
+
*
|
|
90
|
+
* Handles both shapes `BindSerializer::serialize` emits
|
|
91
|
+
* (`stalwartlabs/dns-update`'s `src/bind.rs:44-56`, commit
|
|
92
|
+
* `40e94d85bdbdeeb3a13d4ac8e84a33de5baa6b49`): a short value on one line
|
|
93
|
+
* (`name IN TXT "value"`), and a value over 255 bytes — every RSA DKIM key
|
|
94
|
+
* — split into a parenthesized block of quoted chunks that this
|
|
95
|
+
* reassembles in order.
|
|
96
|
+
*/
|
|
97
|
+
export declare function dkimRecordsFromZoneFile(zoneFile: string): DnsRecordSpec[];
|
|
98
|
+
/**
|
|
99
|
+
* Give an org mail, change its mode, or re-enable a parked one — all the
|
|
100
|
+
* same call. Idempotent: the `Domain` is upserted by `name`, so calling this
|
|
101
|
+
* twice with the same org leaves exactly one `Domain`, and calling it again
|
|
102
|
+
* with a different `mode` changes only the records this returns, never a
|
|
103
|
+
* second `Domain`.
|
|
104
|
+
*
|
|
105
|
+
* Returns the DNS records foundry must publish. This never calls Cloudflare
|
|
106
|
+
* itself — that stays foundry's, by the campaign's non-goals.
|
|
107
|
+
*/
|
|
108
|
+
export declare function applyOrgMail(client: StalwartClient, org: OrgMailOrg, options: OrgMailOptions): Promise<OrgMailResult>;
|
|
109
|
+
/**
|
|
110
|
+
* Stop a domain receiving, keeping every mailbox and message — foundry#7's
|
|
111
|
+
* "park keeps mail, never deletes it". Touches only the `Domain`'s
|
|
112
|
+
* `isEnabled`; no `Account`, no message, ever.
|
|
113
|
+
*
|
|
114
|
+
* A no-op, not a refusal, for an org this instance has never heard of or one
|
|
115
|
+
* already parked: neither sends a request.
|
|
116
|
+
*/
|
|
117
|
+
export declare function parkOrgMail(client: StalwartClient, org: OrgMailOrg, options: OrgMailOptions): Promise<void>;
|