@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 falls back to the shared `resend` route. `removeOrgRelay(client,
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`, a `DnsServer` and a Resend
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`, a `DnsServer` and a Resend
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
- key: 'relay',
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: 'resend' },
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: { else: "'resend'" } },
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 shared-relay default. Org relay routes live on
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`, the Resend relay, `SystemSettings` — is
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`). The shared `resend` route from
159
- * `mailObjects` stays the `else` fallback, so a domain with no relay of its
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 `resend` fallback. */
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
- const FALLBACK_ROUTE = "'resend'";
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 `resend` fallback. */
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.length === 0
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.18.1",
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",