@wtfalch/email 0.14.0 → 0.15.0

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.
@@ -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. `wtfalch.dev`. */
68
+ readonly apex: string;
69
+ /** The MX target and TLS name every domain on this instance shares, e.g. `mail.wtfalch.dev`. */
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.wtfalch.dev` or `selector1._domainkey.acme.wtfalch.dev`. */
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>;