@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';
|
package/dist/postmaster/index.js
CHANGED
|
@@ -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
|
|
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.
|
|
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",
|