@wtfalch/email 0.18.1 → 0.19.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
CHANGED
|
@@ -657,7 +657,9 @@ await parkOrgMail(client, { slug: 'acme', domain: 'acme.com', mode: 'hosted' },
|
|
|
657
657
|
upserts an `MtaRoute` named `lettermint-<slug>` (`smtp.lettermint.co`, port 465,
|
|
658
658
|
implicit TLS, user `lettermint`, the token as a `Value` secret) and rebuilds
|
|
659
659
|
`MtaOutboundStrategy.route` so mail from `domain` leaves through it and every
|
|
660
|
-
other sender
|
|
660
|
+
other sender is delivered direct (route `'mx'`). The expression always starts
|
|
661
|
+
with the rule that delivers a recipient on a hosted domain to its mailbox
|
|
662
|
+
(route `'local'`), whoever the sender is. `removeOrgRelay(client,
|
|
661
663
|
{ slug })` deletes the route and rebuilds; a missing route sends nothing.
|
|
662
664
|
`hasOrgRelay(client, { slug })` is true when the route holds a secret, so a
|
|
663
665
|
caller knows whether it needs a fresh token. The domain is kept in the route's
|
|
@@ -8,8 +8,6 @@ export interface MailObjectsInput {
|
|
|
8
8
|
contact: string;
|
|
9
9
|
/** Container env variable holding the zone-scoped Cloudflare DNS token. */
|
|
10
10
|
dnsTokenVar: string;
|
|
11
|
-
/** Container env variable holding the Resend API key used as SMTP password. */
|
|
12
|
-
resendTokenVar: string;
|
|
13
11
|
/**
|
|
14
12
|
* The project's identity provider, once the mail applications are
|
|
15
13
|
* registered there (wtfalch-manage's docs/plans/email.md E3, and
|
|
@@ -68,8 +66,7 @@ export interface PlatformMailSettingsInput {
|
|
|
68
66
|
/**
|
|
69
67
|
* The platform's own mail settings: Stalwart's default hostname and an OIDC
|
|
70
68
|
* sign-in directory, and nothing else. `mailObjects` cannot stand in for
|
|
71
|
-
* this — it also writes an `AcmeProvider
|
|
72
|
-
* `MtaRoute`, none of which the platform step wants.
|
|
69
|
+
* this — it also writes an `AcmeProvider` and a `DnsServer`, neither of which the platform step wants.
|
|
73
70
|
*
|
|
74
71
|
* A blank `mailHost`, `apex`, `oidc.issuerUrl` or `oidc.audience` throws,
|
|
75
72
|
* naming the field: each reaches a live server, and a blank audience in
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { outboundRoute } from './org-mail.js';
|
|
1
|
+
import { LOCAL_ROUTE, outboundRoute, routeExpression } from './org-mail.js';
|
|
2
2
|
/** A value that names an object created earlier in the same plan. */
|
|
3
3
|
export const ref = (key) => ({ $ref: key });
|
|
4
4
|
const env = (variableName) => ({ '@type': 'EnvironmentVariable', variableName });
|
|
@@ -69,8 +69,7 @@ function validatedClaimUsername(raw) {
|
|
|
69
69
|
/**
|
|
70
70
|
* The platform's own mail settings: Stalwart's default hostname and an OIDC
|
|
71
71
|
* sign-in directory, and nothing else. `mailObjects` cannot stand in for
|
|
72
|
-
* this — it also writes an `AcmeProvider
|
|
73
|
-
* `MtaRoute`, none of which the platform step wants.
|
|
72
|
+
* this — it also writes an `AcmeProvider` and a `DnsServer`, neither of which the platform step wants.
|
|
74
73
|
*
|
|
75
74
|
* A blank `mailHost`, `apex`, `oidc.issuerUrl` or `oidc.audience` throws,
|
|
76
75
|
* naming the field: each reaches a live server, and a blank audience in
|
|
@@ -178,26 +177,18 @@ export function mailObjects(i) {
|
|
|
178
177
|
},
|
|
179
178
|
},
|
|
180
179
|
{
|
|
181
|
-
|
|
180
|
+
// The route expression names this route for every local recipient. If
|
|
181
|
+
// it is missing, Stalwart falls back to the MX lookup without an error.
|
|
182
|
+
key: 'local',
|
|
182
183
|
object: 'MtaRoute',
|
|
183
|
-
match: { name:
|
|
184
|
-
value: {
|
|
185
|
-
'@type': 'Relay',
|
|
186
|
-
name: 'resend',
|
|
187
|
-
description: 'Every outbound message relays through Resend',
|
|
188
|
-
address: 'smtp.resend.com',
|
|
189
|
-
port: 465,
|
|
190
|
-
protocol: 'smtp',
|
|
191
|
-
implicitTls: true,
|
|
192
|
-
authUsername: 'resend',
|
|
193
|
-
authSecret: env(i.resendTokenVar),
|
|
194
|
-
},
|
|
184
|
+
match: { name: LOCAL_ROUTE },
|
|
185
|
+
value: { '@type': 'Local', name: LOCAL_ROUTE },
|
|
195
186
|
},
|
|
196
187
|
{
|
|
197
188
|
key: 'outbound',
|
|
198
189
|
object: 'MtaOutboundStrategy',
|
|
199
190
|
match: { id: 'singleton' },
|
|
200
|
-
value: { route:
|
|
191
|
+
value: { route: routeExpression([]) },
|
|
201
192
|
},
|
|
202
193
|
{
|
|
203
194
|
key: 'system',
|
|
@@ -264,7 +255,7 @@ export async function applyObjects(client, plan, log) {
|
|
|
264
255
|
const ids = {};
|
|
265
256
|
for (const p of plan) {
|
|
266
257
|
const value = resolve(p.value, ids);
|
|
267
|
-
// The plan's route is the
|
|
258
|
+
// The plan's route is the direct-delivery default. Org relay routes live on
|
|
268
259
|
// the server, so they are rebuilt here rather than overwritten.
|
|
269
260
|
if (p.object === 'MtaOutboundStrategy')
|
|
270
261
|
value.route = await outboundRoute(client);
|
|
@@ -5,7 +5,7 @@ import type { StalwartClient } from './client.js';
|
|
|
5
5
|
* never a second Stalwart, never a per-org instance.
|
|
6
6
|
*
|
|
7
7
|
* **What this does and does not touch.** The shared instance itself —
|
|
8
|
-
* `AcmeProvider`, `DnsServer`,
|
|
8
|
+
* `AcmeProvider`, `DnsServer`, `SystemSettings` — is
|
|
9
9
|
* provisioned once, by `mailObjects`/`applyObjects` in `./objects.ts`. This
|
|
10
10
|
* module only upserts the one `Domain` object an org needs on top of that,
|
|
11
11
|
* confirmed against `stalwartlabs/stalwart` at commit
|
|
@@ -155,9 +155,8 @@ export declare function applyOrgMail(client: StalwartClient, org: OrgMailOrg, op
|
|
|
155
155
|
export declare function parkOrgMail(client: StalwartClient, org: OrgMailOrg, options: OrgMailOptions): Promise<void>;
|
|
156
156
|
/**
|
|
157
157
|
* One org's outgoing mail through its own Lettermint credential, limited to
|
|
158
|
-
* that org's domain (`wtfalch/email#118`).
|
|
159
|
-
*
|
|
160
|
-
* own still sends.
|
|
158
|
+
* that org's domain (`wtfalch/email#118`). Direct delivery stays the `else`
|
|
159
|
+
* fallback, so a domain with no relay of its own still sends.
|
|
161
160
|
*
|
|
162
161
|
* Each org gets an `MtaRoute` named `lettermint-<slug>`. The domain it
|
|
163
162
|
* serves is stored in the route's `description`, because that is the only
|
|
@@ -178,9 +177,17 @@ export interface OrgRelayInput extends OrgRelayOrg {
|
|
|
178
177
|
/** The Lettermint project token. Sent as `@type: Value` and never logged or thrown. */
|
|
179
178
|
readonly secret: string;
|
|
180
179
|
}
|
|
180
|
+
/** The `MtaRoute` that writes a message into this server's own mailboxes. */
|
|
181
|
+
export declare const LOCAL_ROUTE = "local";
|
|
182
|
+
/** The route expression for a set of relays: local delivery first, then each
|
|
183
|
+
* relay by sender domain, then direct delivery. */
|
|
184
|
+
export declare function routeExpression(relays: readonly {
|
|
185
|
+
domain: string;
|
|
186
|
+
name: string;
|
|
187
|
+
}[]): Record<string, unknown>;
|
|
181
188
|
/** The `MtaOutboundStrategy.route` expression for the relays that exist now.
|
|
182
189
|
* `applyObjects` uses it too, so a re-apply of the instance plan keeps every
|
|
183
|
-
* org's route instead of resetting the expression to the
|
|
190
|
+
* org's route instead of resetting the expression to the direct fallback. */
|
|
184
191
|
export declare function outboundRoute(client: StalwartClient): Promise<Record<string, unknown>>;
|
|
185
192
|
/**
|
|
186
193
|
* Give an org its own Lettermint relay, or replace its token. Idempotent: the
|
|
@@ -209,7 +209,10 @@ export async function parkOrgMail(client, org, options) {
|
|
|
209
209
|
}
|
|
210
210
|
const RELAY_PREFIX = 'lettermint-';
|
|
211
211
|
const RELAY_DESCRIPTION = 'Lettermint relay for ';
|
|
212
|
-
|
|
212
|
+
/** Stalwart's built-in route for direct delivery by MX lookup. */
|
|
213
|
+
const FALLBACK_ROUTE = "'mx'";
|
|
214
|
+
/** The `MtaRoute` that writes a message into this server's own mailboxes. */
|
|
215
|
+
export const LOCAL_ROUTE = 'local';
|
|
213
216
|
function relayName(slug) {
|
|
214
217
|
assertLabel('an org slug', slug);
|
|
215
218
|
return `${RELAY_PREFIX}${slug}`;
|
|
@@ -242,9 +245,27 @@ function routeRule(domain, routeName) {
|
|
|
242
245
|
['then', `'${routeName}'`],
|
|
243
246
|
]);
|
|
244
247
|
}
|
|
248
|
+
/** The first rule of every route expression: a recipient on a domain this
|
|
249
|
+
* server hosts is delivered here. Without it the message follows the sender's
|
|
250
|
+
* relay or the MX lookup, and never reaches the mailbox. */
|
|
251
|
+
function localRule() {
|
|
252
|
+
return Object.fromEntries([
|
|
253
|
+
['if', 'is_local_domain(rcpt_domain)'],
|
|
254
|
+
['then', `'${LOCAL_ROUTE}'`],
|
|
255
|
+
]);
|
|
256
|
+
}
|
|
257
|
+
/** The route expression for a set of relays: local delivery first, then each
|
|
258
|
+
* relay by sender domain, then direct delivery. */
|
|
259
|
+
export function routeExpression(relays) {
|
|
260
|
+
const rules = [localRule(), ...relays.map((e) => routeRule(e.domain, e.name))];
|
|
261
|
+
return {
|
|
262
|
+
match: Object.fromEntries(rules.map((r, i) => [String(i), r])),
|
|
263
|
+
else: FALLBACK_ROUTE,
|
|
264
|
+
};
|
|
265
|
+
}
|
|
245
266
|
/** The `MtaOutboundStrategy.route` expression for the relays that exist now.
|
|
246
267
|
* `applyObjects` uses it too, so a re-apply of the instance plan keeps every
|
|
247
|
-
* org's route instead of resetting the expression to the
|
|
268
|
+
* org's route instead of resetting the expression to the direct fallback. */
|
|
248
269
|
export async function outboundRoute(client) {
|
|
249
270
|
const entries = (await listRelays(client))
|
|
250
271
|
.flatMap((r) => {
|
|
@@ -252,14 +273,15 @@ export async function outboundRoute(client) {
|
|
|
252
273
|
return domain && r.name ? [{ domain, name: r.name }] : [];
|
|
253
274
|
})
|
|
254
275
|
.sort((a, b) => a.name.localeCompare(b.name));
|
|
255
|
-
return entries
|
|
256
|
-
? { else: FALLBACK_ROUTE }
|
|
257
|
-
: {
|
|
258
|
-
match: Object.fromEntries(entries.map((e, i) => [String(i), routeRule(e.domain, e.name)])),
|
|
259
|
-
else: FALLBACK_ROUTE,
|
|
260
|
-
};
|
|
276
|
+
return routeExpression(entries);
|
|
261
277
|
}
|
|
262
278
|
async function rebuildRoute(client) {
|
|
279
|
+
// The expression names the local route. On a server without it Stalwart
|
|
280
|
+
// falls back to the MX lookup for its own recipients, without an error.
|
|
281
|
+
const routes = await client.list('MtaRoute');
|
|
282
|
+
if (!routes.some((r) => r.name === LOCAL_ROUTE)) {
|
|
283
|
+
await client.create('MtaRoute', { '@type': 'Local', name: LOCAL_ROUTE });
|
|
284
|
+
}
|
|
263
285
|
const route = await outboundRoute(client);
|
|
264
286
|
await client.update('MtaOutboundStrategy', 'singleton', { route });
|
|
265
287
|
await client.create('Action', { '@type': 'ReloadSettings' });
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wtfalch/email",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.19.1",
|
|
4
4
|
"description": "The wtfalch estate: reading a mailbox over JMAP, administering the Stalwart server it lives on, and iTIP scheduling over iMIP. Three entries with no code in common.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|