@wtfalch/email 0.16.0 → 0.17.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.
@@ -17,7 +17,7 @@
17
17
  export { API_KEY_PREFIX, DASHBOARD_PERMISSIONS, StalwartClient, StalwartError, authFor, type Credential, type SessionInfo, type StalwartAuth, } from './client.js';
18
18
  export { type Instance, InstanceRefused, openInstance, type RefusalReason } from './instance.js';
19
19
  export { loadOverview } from './load.js';
20
- export { FUTURE_RELEASE, applyObjects, mailObjects, ref, type MailObjectsInput, type PlannedObject, } from './objects.js';
20
+ export { FUTURE_RELEASE, applyObjects, mailObjects, platformMailSettingsObjects, ref, type MailObjectsInput, type PlannedObject, type PlatformMailSettingsInput, } from './objects.js';
21
21
  export { planMailboxes, withPassword } from './mailboxes.js';
22
22
  export { overview, pickDomain, type AccountView, type CredentialSummary, type DomainView, type Managed, type Overview, type OverviewInput, type PeopleView, type Person, type WireAccount, type WireAlias, type WireDomain, type WireSystemSettings, } from './overview.js';
23
23
  export { MailWriteRefused, membershipIds, newAccount, newGroup, withAlias, withMembership, withoutAlias, withoutApiKey, withoutAppPassword, withoutMembership, } from './writes.js';
@@ -17,7 +17,7 @@
17
17
  export { API_KEY_PREFIX, DASHBOARD_PERMISSIONS, StalwartClient, StalwartError, authFor, } from './client.js';
18
18
  export { InstanceRefused, openInstance } from './instance.js';
19
19
  export { loadOverview } from './load.js';
20
- export { FUTURE_RELEASE, applyObjects, mailObjects, ref, } from './objects.js';
20
+ export { FUTURE_RELEASE, applyObjects, mailObjects, platformMailSettingsObjects, ref, } from './objects.js';
21
21
  export { planMailboxes, withPassword } from './mailboxes.js';
22
22
  export { overview, pickDomain, } from './overview.js';
23
23
  export { MailWriteRefused, membershipIds, newAccount, newGroup, withAlias, withMembership, withoutAlias, withoutApiKey, withoutAppPassword, withoutMembership, } from './writes.js';
@@ -53,6 +53,30 @@ export interface PlannedObject {
53
53
  match: Record<string, unknown>;
54
54
  value: Record<string, unknown>;
55
55
  }
56
+ export interface PlatformMailSettingsInput {
57
+ /** The platform's own apex domain, written lowercased as `usernameDomain`. */
58
+ apex: string;
59
+ /** The MX target and TLS name, e.g. `mx.example.com`. */
60
+ mailHost: string;
61
+ oidc: {
62
+ issuerUrl: string;
63
+ audience: string;
64
+ requireScopes?: Record<string, boolean>;
65
+ claimUsername?: string;
66
+ };
67
+ }
68
+ /**
69
+ * The platform's own mail settings: Stalwart's default hostname and an OIDC
70
+ * 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.
73
+ *
74
+ * A blank `mailHost`, `apex`, `oidc.issuerUrl` or `oidc.audience` throws,
75
+ * naming the field: each reaches a live server, and a blank audience in
76
+ * particular lets Stalwart skip the audience check, so any token from the
77
+ * issuer would sign in.
78
+ */
79
+ export declare function platformMailSettingsObjects(input: PlatformMailSettingsInput): PlannedObject[];
56
80
  /**
57
81
  * `MtaExtensions.futureRelease`: how long the server will hold a message
58
82
  * before sending it. It gates the SMTP FUTURERELEASE extension. Empty by
@@ -2,6 +2,115 @@ import { outboundRoute } 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 });
5
+ /**
6
+ * The `Directory` of `@type: 'Oidc'` that signs people in against an
7
+ * identity provider, in the one field shape both `mailObjects` (an org
8
+ * domain) and `platformMailSettingsObjects` (the platform's own server)
9
+ * write it in. Shared so the two never drift apart.
10
+ */
11
+ function oidcDirectoryObject(apex, oidc) {
12
+ const description = `${oidc.issuerUrl} (${apex})`;
13
+ return {
14
+ key: 'oidc',
15
+ object: 'Directory',
16
+ match: { description },
17
+ value: {
18
+ '@type': 'Oidc',
19
+ description,
20
+ issuerUrl: oidc.issuerUrl,
21
+ requireAudience: oidc.audience,
22
+ requireScopes: oidc.requireScopes ?? {},
23
+ claimUsername: oidc.claimUsername ?? 'preferred_username',
24
+ usernameDomain: apex,
25
+ claimName: 'name',
26
+ },
27
+ };
28
+ }
29
+ function requireNonBlank(value, fieldName) {
30
+ const trimmed = value.trim();
31
+ if (!trimmed)
32
+ throw new Error(`platformMailSettingsObjects: "${fieldName}" must not be blank`);
33
+ return trimmed;
34
+ }
35
+ /**
36
+ * Stalwart compares `iss` as a plain string, and the Directory's `match` key
37
+ * is built from the raw issuer, so a respelling of the same issuer creates a
38
+ * second Directory instead of updating the first. This rejects every
39
+ * respelling rather than normalising it: a non-canonical issuer in the
40
+ * caller's config is a configuration bug worth surfacing, not silently
41
+ * fixing up.
42
+ */
43
+ function validatedIssuerUrl(raw) {
44
+ const issuerUrl = requireNonBlank(raw, 'oidc.issuerUrl');
45
+ if (issuerUrl.endsWith('/')) {
46
+ throw new Error('platformMailSettingsObjects: "oidc.issuerUrl" must not end with a trailing slash');
47
+ }
48
+ let url;
49
+ try {
50
+ url = new URL(issuerUrl);
51
+ }
52
+ catch {
53
+ throw new Error('platformMailSettingsObjects: "oidc.issuerUrl" must be a valid URL');
54
+ }
55
+ if (url.protocol !== 'https:') {
56
+ throw new Error('platformMailSettingsObjects: "oidc.issuerUrl" must be https');
57
+ }
58
+ const canonical = url.origin + (url.pathname === '/' ? '' : url.pathname);
59
+ if (canonical !== issuerUrl) {
60
+ throw new Error('platformMailSettingsObjects: "oidc.issuerUrl" must be in canonical form (no case, userinfo, query, fragment, or respelling)');
61
+ }
62
+ return issuerUrl;
63
+ }
64
+ function validatedClaimUsername(raw) {
65
+ if (raw === undefined)
66
+ return 'preferred_username';
67
+ return requireNonBlank(raw, 'oidc.claimUsername');
68
+ }
69
+ /**
70
+ * The platform's own mail settings: Stalwart's default hostname and an OIDC
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.
74
+ *
75
+ * A blank `mailHost`, `apex`, `oidc.issuerUrl` or `oidc.audience` throws,
76
+ * naming the field: each reaches a live server, and a blank audience in
77
+ * particular lets Stalwart skip the audience check, so any token from the
78
+ * issuer would sign in.
79
+ */
80
+ export function platformMailSettingsObjects(input) {
81
+ const mailHost = requireNonBlank(input.mailHost, 'mailHost');
82
+ const apex = requireNonBlank(input.apex, 'apex').toLowerCase();
83
+ const issuerUrl = validatedIssuerUrl(input.oidc.issuerUrl);
84
+ const audience = requireNonBlank(input.oidc.audience, 'oidc.audience');
85
+ const claimUsername = validatedClaimUsername(input.oidc.claimUsername);
86
+ const directory = oidcDirectoryObject(apex, {
87
+ issuerUrl,
88
+ audience,
89
+ requireScopes: input.oidc.requireScopes,
90
+ claimUsername,
91
+ });
92
+ return [
93
+ {
94
+ key: 'system',
95
+ object: 'SystemSettings',
96
+ match: { id: 'singleton' },
97
+ value: { defaultHostname: mailHost },
98
+ },
99
+ directory,
100
+ {
101
+ key: 'auth',
102
+ object: 'Authentication',
103
+ match: { id: 'singleton' },
104
+ value: { directoryId: ref('oidc') },
105
+ },
106
+ {
107
+ key: 'reload',
108
+ object: 'Action',
109
+ match: {},
110
+ value: { '@type': 'ReloadSettings' },
111
+ },
112
+ ];
113
+ }
5
114
  /**
6
115
  * `MtaExtensions.futureRelease`: how long the server will hold a message
7
116
  * before sending it. It gates the SMTP FUTURERELEASE extension. Empty by
@@ -21,26 +130,7 @@ export const FUTURE_RELEASE = { else: "'30d'" };
21
130
  * server. What each object is for is in wtfalch-manage's docs/plans/email.md (E3 to E5).
22
131
  */
23
132
  export function mailObjects(i) {
24
- const oidcDescription = i.oidc ? `${i.oidc.issuerUrl} (${i.apex})` : undefined;
25
- const directory = i.oidc
26
- ? [
27
- {
28
- key: 'oidc',
29
- object: 'Directory',
30
- match: { description: oidcDescription },
31
- value: {
32
- '@type': 'Oidc',
33
- description: oidcDescription,
34
- issuerUrl: i.oidc.issuerUrl,
35
- requireAudience: i.oidc.audience,
36
- requireScopes: i.oidc.requireScopes ?? {},
37
- claimUsername: i.oidc.claimUsername ?? 'preferred_username',
38
- usernameDomain: i.apex,
39
- claimName: 'name',
40
- },
41
- },
42
- ]
43
- : [];
133
+ const directory = i.oidc ? [oidcDirectoryObject(i.apex, i.oidc)] : [];
44
134
  return [
45
135
  {
46
136
  key: 'acme',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wtfalch/email",
3
- "version": "0.16.0",
3
+ "version": "0.17.0",
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",