domma-cms 1.28.4 → 1.29.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.
Files changed (98) hide show
  1. package/CHANGELOG.md +5 -0
  2. package/admin/js/lib/contacts-arrange.js +1 -1
  3. package/docs/DommaFeatures.md +5 -3
  4. package/package.json +4 -1
  5. package/plugins/_lib/admin/mail/body-menu.js +2 -0
  6. package/plugins/_lib/admin/mail/cms-host.js +22 -0
  7. package/plugins/_lib/admin/mail/compose-window.js +1027 -1021
  8. package/plugins/_lib/admin/mail/contacts.js +10 -8
  9. package/plugins/_lib/admin/mail/diagnostics-section.js +2 -0
  10. package/plugins/_lib/admin/mail/drag-drop.js +46 -0
  11. package/plugins/_lib/admin/mail/folder-tree.js +2 -0
  12. package/plugins/_lib/admin/mail/font-controls.js +6 -4
  13. package/plugins/_lib/admin/mail/fonts.js +1 -1
  14. package/plugins/_lib/admin/mail/host-context.js +87 -0
  15. package/plugins/_lib/admin/mail/identity.js +2 -0
  16. package/plugins/_lib/admin/mail/image-senders-section.js +2 -0
  17. package/plugins/_lib/admin/mail/keyboard.js +2 -0
  18. package/plugins/_lib/admin/mail/mail.css +1 -1
  19. package/plugins/_lib/admin/mail/mail.html +4 -0
  20. package/plugins/_lib/admin/mail/message-actions.js +2 -0
  21. package/plugins/_lib/admin/mail/oauth-panel.js +2 -0
  22. package/plugins/_lib/admin/mail/panes.js +2 -0
  23. package/plugins/_lib/admin/mail/reader-kit.js +2 -0
  24. package/plugins/_lib/admin/mail/reader-runtime.js +6534 -0
  25. package/plugins/_lib/admin/mail/reader-view.js +9 -6380
  26. package/plugins/_lib/admin/mail/resizable.js +2 -0
  27. package/plugins/_lib/admin/mail/restore-spam.js +13 -0
  28. package/plugins/_lib/admin/mail/rules.js +14 -0
  29. package/plugins/_lib/admin/mail/scheduling.js +4 -1
  30. package/plugins/_lib/admin/mail/section-kit.js +4 -1
  31. package/plugins/_lib/admin/mail/security-note.js +2 -0
  32. package/plugins/_lib/admin/mail/settings-section.js +11 -10
  33. package/plugins/_lib/admin/mail/templates.js +5 -2
  34. package/plugins/_lib/admin/mail/threads.js +2 -0
  35. package/plugins/_lib/admin/mail/vacation.js +16 -2
  36. package/plugins/_lib/admin/mail/when-closed.js +24 -2
  37. package/plugins/_lib/admin/ui/dates.js +2 -0
  38. package/plugins/_lib/admin/ui/resizable.js +7 -5
  39. package/plugins/_lib/contacts/mailContact.js +69 -0
  40. package/plugins/_lib/contacts/model.js +199 -0
  41. package/plugins/_lib/domma-mail-contacts.lock.json +10 -0
  42. package/plugins/_lib/domma-mail.lock.json +85 -0
  43. package/plugins/_lib/mail/accountFileStore.js +66 -0
  44. package/plugins/_lib/mail/accountRepository.js +617 -0
  45. package/plugins/_lib/mail/accountRoutes.js +130 -0
  46. package/plugins/_lib/mail/accounts.js +66 -940
  47. package/plugins/_lib/mail/automationLock.js +10 -0
  48. package/plugins/_lib/mail/bodyTokenProvider.js +36 -0
  49. package/plugins/_lib/mail/bodyTokens.js +5 -99
  50. package/plugins/_lib/mail/compose.js +5 -3
  51. package/plugins/_lib/mail/defaults.js +2 -0
  52. package/plugins/_lib/mail/envelope.js +3 -1
  53. package/plugins/_lib/mail/folderActions.js +83 -0
  54. package/plugins/_lib/mail/folderRuntime.js +109 -0
  55. package/plugins/_lib/mail/folders.js +4 -9
  56. package/plugins/_lib/mail/imapPool.js +11 -389
  57. package/plugins/_lib/mail/imapPoolRuntime.js +396 -0
  58. package/plugins/_lib/mail/mbox.js +2 -0
  59. package/plugins/_lib/mail/message-action.js +2 -0
  60. package/plugins/_lib/mail/messageSecurity.js +4 -111
  61. package/plugins/_lib/mail/messageSecurityProvider.js +116 -0
  62. package/plugins/_lib/mail/networkAddresses.js +77 -0
  63. package/plugins/_lib/mail/networkPolicy.js +62 -0
  64. package/plugins/_lib/mail/oauth.js +3 -451
  65. package/plugins/_lib/mail/oauthAccounts.js +178 -0
  66. package/plugins/_lib/mail/oauthRouteRuntime.js +282 -0
  67. package/plugins/_lib/mail/oauthRoutes.js +7 -289
  68. package/plugins/_lib/mail/oauthRuntime.js +456 -0
  69. package/plugins/_lib/mail/pollSchedule.js +2 -0
  70. package/plugins/_lib/mail/poller.js +4 -136
  71. package/plugins/_lib/mail/pollerRuntime.js +150 -0
  72. package/plugins/_lib/mail/priority.js +2 -0
  73. package/plugins/_lib/mail/publicMailbox.js +27 -0
  74. package/plugins/_lib/mail/readRoutes.js +14 -827
  75. package/plugins/_lib/mail/readRuntime.js +701 -0
  76. package/plugins/_lib/mail/render.js +2 -0
  77. package/plugins/_lib/mail/ruleRunner.js +27 -10
  78. package/plugins/_lib/mail/scheduler.js +11 -279
  79. package/plugins/_lib/mail/schedulerRuntime.js +259 -0
  80. package/plugins/_lib/mail/secretProvider.js +112 -0
  81. package/plugins/_lib/mail/secretbox.js +12 -225
  82. package/plugins/_lib/mail/send.js +21 -537
  83. package/plugins/_lib/mail/sieve.js +211 -0
  84. package/plugins/_lib/mail/sieveHost.js +24 -0
  85. package/plugins/_lib/mail/smtpService.js +553 -0
  86. package/plugins/_lib/mail/snoozeRuntime.js +60 -0
  87. package/plugins/_lib/mail/store.js +122 -64
  88. package/plugins/_lib/mail/subscriptions.js +11 -0
  89. package/plugins/_lib/mail/sync.js +64 -290
  90. package/plugins/_lib/mail/syncPlan.js +2 -0
  91. package/plugins/_lib/mail/syncRuntime.js +255 -0
  92. package/plugins/_lib/mail/syncSelection.js +2 -0
  93. package/plugins/_lib/mail/unreadBadge.js +2 -0
  94. package/plugins/_lib/mail/unsubscribe.js +2 -0
  95. package/plugins/_lib/mail/vacationRunner.js +3 -116
  96. package/plugins/_lib/mail/vacationRuntime.js +70 -0
  97. package/plugins/_lib/mail/write.js +44 -13
  98. package/server/routes/api/contacts.js +2 -196
@@ -0,0 +1,77 @@
1
+ // Source: @domma-mail/core 0.18.0, packages/core/src/mail/networkAddresses.js.
2
+ // Update with domma-mail/scripts/sync-cms.mjs; edit the shared source.
3
+ /** Address classification from the CMS outbound policy, MIT licensed. */
4
+ import net from 'node:net';
5
+
6
+ const V4_BLOCKED = [
7
+ ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16], ['172.16.0.0', 12],
8
+ ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.88.99.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15],
9
+ ['198.51.100.0', 24], ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4]
10
+ ];
11
+
12
+ function v4ToInt(ip) {
13
+ const p = String(ip).split('.').map(Number);
14
+ if (p.length !== 4 || p.some(n => !Number.isInteger(n) || n < 0 || n > 255)) return null;
15
+ return ((p[0] << 24) >>> 0) + (p[1] << 16) + (p[2] << 8) + p[3];
16
+ }
17
+
18
+ function v4InRange(n, base, bits) {
19
+ const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
20
+ return ((n & mask) >>> 0) === ((v4ToInt(base) & mask) >>> 0);
21
+ }
22
+
23
+ function v4Blocked(ip) {
24
+ const n = v4ToInt(ip);
25
+ if (n === null) return true;
26
+ return V4_BLOCKED.some(([base, bits]) => v4InRange(n, base, bits));
27
+ }
28
+
29
+ /** Expand an IPv6 address to 8 groups of numbers (null when it is not one). */
30
+ function v6Groups(ip) {
31
+ let s = String(ip).toLowerCase().split('%')[0];
32
+ // A dotted IPv4 tail (::ffff:1.2.3.4).
33
+ const tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(s);
34
+ if (tail) {
35
+ const n = v4ToInt(tail[1]);
36
+ if (n === null) return null;
37
+ s = s.slice(0, -tail[1].length) + `${(n >>> 16).toString(16)}:${(n & 0xffff).toString(16)}`;
38
+ }
39
+ const halves = s.split('::');
40
+ if (halves.length > 2) return null;
41
+ const left = halves[0] ? halves[0].split(':') : [];
42
+ const right = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
43
+ const fill = halves.length === 2 ? 8 - left.length - right.length : 0;
44
+ const groups = [...left, ...Array(Math.max(0, fill)).fill('0'), ...right].map(g => Number.parseInt(g || '0', 16));
45
+ return groups.length === 8 && groups.every(g => Number.isInteger(g) && g >= 0 && g <= 0xffff) ? groups : null;
46
+ }
47
+
48
+ /**
49
+ * Is this address one a server-side fetch must never reach?
50
+ *
51
+ * @param {string} ip
52
+ * @returns {boolean}
53
+ */
54
+ export function isBlockedAddress(ip) {
55
+ const kind = net.isIP(String(ip || ''));
56
+ if (kind === 4) return v4Blocked(ip);
57
+ if (kind !== 6) return true;
58
+ const g = v6Groups(ip);
59
+ if (!g) return true;
60
+ const embeddedV4 = () => `${g[6] >> 8}.${g[6] & 255}.${g[7] >> 8}.${g[7] & 255}`;
61
+ if (g.every(x => x === 0)) return true; // ::
62
+ if (g.slice(0, 7).every(x => x === 0) && g[7] === 1) return true; // ::1
63
+ if (g.slice(0, 5).every(x => x === 0) && g[5] === 0xffff) return v4Blocked(embeddedV4()); // ::ffff:a.b.c.d
64
+ if (g.slice(0, 4).every(x => x === 0) && g[4] === 0xffff && g[5] === 0) return true; // ::ffff:0:0/96 (SIIT)
65
+ if (g[0] === 0x64 && g[1] === 0xff9b && g[2] === 1) return true; // 64:ff9b:1::/48 (local NAT64)
66
+ if (g[0] === 0x100 && g[1] === 0 && g[2] === 0 && g[3] === 0) return true; // 100::/64 (discard)
67
+ if (g.slice(0, 6).every(x => x === 0)) return true; // ::a.b.c.d (deprecated compat)
68
+ if (g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every(x => x === 0)) return v4Blocked(embeddedV4()); // NAT64
69
+ if ((g[0] & 0xfe00) === 0xfc00) return true; // fc00::/7 unique local
70
+ if ((g[0] & 0xffc0) === 0xfe80) return true; // fe80::/10 link-local
71
+ if ((g[0] & 0xffc0) === 0xfec0) return true; // fec0::/10 site-local
72
+ if ((g[0] & 0xff00) === 0xff00) return true; // multicast
73
+ if (g[0] === 0x2001 && g[1] === 0x0db8) return true; // documentation
74
+ if (g[0] === 0x2002) return v4Blocked(`${g[1] >> 8}.${g[1] & 255}.${g[2] >> 8}.${g[2] & 255}`); // 6to4
75
+ if (g[0] === 0x2001 && g[1] === 0) return true; // Teredo
76
+ return false;
77
+ }
@@ -0,0 +1,62 @@
1
+ // Source: @domma-mail/core 0.18.0, packages/core/src/mail/networkPolicy.js.
2
+ // Update with domma-mail/scripts/sync-cms.mjs; edit the shared source.
3
+ import dns from 'node:dns/promises';
4
+ import net from 'node:net';
5
+ import {isBlockedAddress} from './networkAddresses.js';
6
+
7
+ const PORTS = {imap: [143, 993], smtp: [25, 465, 587, 2525], sieve: [4190]};
8
+ const LOOPBACK = {localhost: '127.0.0.1', '127.0.0.1': '127.0.0.1', '::1': '::1'};
9
+
10
+ export class MailHostRefused extends Error {
11
+ constructor(message = 'That mail server is on a private network, so this application will not connect to it.') {
12
+ super(message);
13
+ this.mailHostRefused = true;
14
+ this.code = 'EMAILHOST_REFUSED';
15
+ }
16
+ }
17
+
18
+ export function normaliseHost(host) {
19
+ return String(host ?? '').trim().toLowerCase().replace(/\.$/, '').replace(/^\[(.*)\]$/, '$1');
20
+ }
21
+
22
+ /** Resolve once, validate every answer and connect to the selected address. */
23
+ export function createMailHostPolicy({getPolicy = () => ({}), lookup = dns.lookup} = {}) {
24
+ async function pinMailHost(host, port, options = {}) {
25
+ const hostPolicy = getPolicy();
26
+ const policy = {...hostPolicy, ...options, signed: hostPolicy.signed === true || options.signed === true};
27
+ const name = normaliseHost(host);
28
+ const kind = policy.kind ?? 'imap';
29
+ const number = Number(port);
30
+ if (!name || /[\s/\\@\0]/.test(name)) throw new MailHostRefused('A valid mail server hostname is required.');
31
+ if (!policy.anyPort && (!Number.isInteger(number) || number < 1 || number > 65535)) throw new MailHostRefused('A valid mail server port is required.');
32
+ if (policy.signed && !policy.anyPort && !(PORTS[kind] ?? []).includes(number)) throw new MailHostRefused('That port is not used for mail here.');
33
+ const servername = net.isIP(name) ? undefined : name;
34
+ if (policy.signed && Object.hasOwn(LOOPBACK, name)) {
35
+ const address = LOOPBACK[name];
36
+ return {address, family: net.isIP(address), servername};
37
+ }
38
+ const exempt = !policy.signed && (policy.allowPrivate === true
39
+ || (policy.ownSmtpHost && normaliseHost(policy.ownSmtpHost) === name));
40
+ if (!exempt && (name === 'localhost' || /\.(local|internal|localhost|home|lan|intranet)$/.test(name))) throw new MailHostRefused();
41
+ const results = net.isIP(name) ? [{address: name, family: net.isIP(name)}] : await lookup(name, {all: true, verbatim: true});
42
+ if (!Array.isArray(results) || !results.length) throw Object.assign(new Error('Mail server hostname could not be resolved.'), {code: 'ENOTFOUND'});
43
+ const answers = results.map(item => typeof item === 'string' ? {address: item, family: net.isIP(item)} : item);
44
+ if (answers.some(item => !net.isIP(item?.address))) throw new MailHostRefused('The mail server returned an invalid network address.');
45
+ if (!exempt && answers.some(item => isBlockedAddress(item.address))) throw new MailHostRefused();
46
+ return {address: answers[0].address, family: net.isIP(answers[0].address), servername};
47
+ }
48
+
49
+ async function checkMailHost(host, options = {}) {
50
+ try {
51
+ await pinMailHost(host, options.port, {...options, anyPort: options.port === undefined});
52
+ return {ok: true};
53
+ } catch (error) {
54
+ if (error.mailHostRefused) return {ok: false, error: error.message};
55
+ // Saving unresolvable details is allowed, but connection tests must
56
+ // still resolve and pin successfully before opening any socket.
57
+ if (['ENOTFOUND', 'EAI_AGAIN', 'ENODATA'].includes(error.code)) return {ok: true};
58
+ throw error;
59
+ }
60
+ }
61
+ return {pinMailHost, checkMailHost};
62
+ }
@@ -1,453 +1,5 @@
1
- /**
2
- * OAuth2 sign-in for mailboxes (XOAUTH2) - Microsoft 365 / Outlook.com and Gmail.
3
- *
4
- * A mailbox can be signed in with the provider instead of a password: no app
5
- * password, and a sign-in the provider can withdraw. The customer registers
6
- * THEIR OWN app with the provider (the Docs Pro cloud-copies design) - the
7
- * site never holds a client id of ours, so nobody else's app or verification
8
- * stands between a customer and their own mail.
9
- *
10
- * What is kept (sealed with secretbox, the same key as mailbox passwords):
11
- * the client secret, the refresh token and the current access token.
12
- *
13
- * ## Refreshing
14
- *
15
- * An access token lasts about an hour. It is renewed at the point of use, not
16
- * on a timer: IMAP and SMTP only present it when a connection is opened, and
17
- * a pooled IMAP connection stays signed in after its token has expired.
18
- *
19
- * - before expiry: `toConnection()` carries `expiresAt` and a `refresh`
20
- * function; the pool renews when under a minute is left.
21
- * - on an auth failure: the pool (and nodemailer, through its
22
- * `provisionCallback`) asks for a forced renewal and tries ONCE more.
23
- *
24
- * A refresh the provider REFUSES (invalid_grant and friends - revoked,
25
- * expired, a Google "Testing" app's 7-day limit, a client secret that ran
26
- * out) marks the account "needs reconnecting" and tells its owner. From then
27
- * on `toConnection()` throws OAuthReconnectError without touching the network,
28
- * so the poller cannot hammer a dead sign-in. A refresh that merely could not
29
- * be done (network, 5xx) changes nothing and is tried again next time.
30
- *
31
- * Microsoft ROTATES refresh tokens: every refresh may answer a new one, and the
32
- * new one is saved. Google answers none on refresh; the stored one is kept.
33
- *
34
- * Endpoints and scopes from the vendors' documentation (2026-10):
35
- * - learn.microsoft.com .../v2-oauth2-auth-code-flow and
36
- * .../how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth
37
- * - developers.google.com .../oauth2/web-server and .../gmail/imap/xoauth2-protocol
38
- *
39
- * @module _lib/mail/oauth
40
- */
41
- import {createHash, randomBytes} from 'node:crypto';
42
-
43
1
  import * as accounts from './accounts.js';
44
2
  import {OAuthReconnectError} from './accounts.js';
45
- import {open, seal} from './secretbox.js';
46
-
47
- /** The tenant id Microsoft gives every personal (Outlook.com) account in an id_token. */
48
- const MS_CONSUMER_TENANT = '9188040d-6c67-4c5b-b112-36a304b66dad';
49
-
50
- /** Renew when less than this is left, so a token never expires mid-handshake. */
51
- export const REFRESH_SKEW_MS = 60_000;
52
-
53
- const MS_MAIL_SCOPES = ['https://outlook.office.com/IMAP.AccessAsUser.All', 'https://outlook.office.com/SMTP.Send'];
54
-
55
- /**
56
- * The two providers. Hosts are fixed: the token only works against the
57
- * provider's own servers, so there is nothing for the customer to type and no
58
- * host to guard.
59
- */
60
- export const PROVIDERS = {
61
- microsoft: {
62
- id: 'microsoft',
63
- label: 'Microsoft 365 / Outlook.com',
64
- short: 'Microsoft',
65
- needsTenant: true,
66
- authorizeUrl: (tenant) => `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/authorize`,
67
- tokenUrl: (tenant) => `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/token`,
68
- // openid + email only to learn the address signed in; all the mail
69
- // scopes are one resource (outlook.office.com), which Microsoft
70
- // requires of a single token.
71
- scopes: [...MS_MAIL_SCOPES, 'offline_access', 'openid', 'email'],
72
- refreshScope: [...MS_MAIL_SCOPES, 'offline_access'].join(' '),
73
- // Recommended for confidential clients too (the auth-code-flow page).
74
- pkce: true,
75
- extraAuthParams: {response_mode: 'query', prompt: 'select_account'},
76
- imap: {host: 'outlook.office365.com', port: 993, secure: true},
77
- smtp: {host: 'smtp.office365.com', port: 587, secure: false},
78
- // Outlook.com's own outgoing server (support.microsoft.com, Outlook.com settings).
79
- smtpPersonal: {host: 'smtp-mail.outlook.com', port: 587, secure: false},
80
- // Microsoft offers no endpoint for an app to hand one refresh token back.
81
- revokeUrl: null
82
- },
83
- google: {
84
- id: 'google',
85
- label: 'Gmail / Google Workspace',
86
- short: 'Google',
87
- needsTenant: false,
88
- authorizeUrl: () => 'https://accounts.google.com/o/oauth2/v2/auth',
89
- tokenUrl: () => 'https://oauth2.googleapis.com/token',
90
- scopes: ['https://mail.google.com/', 'openid', 'email'],
91
- refreshScope: null,
92
- // PKCE as well as state + secret (Google accepts S256 code_challenge).
93
- pkce: true,
94
- // offline + consent, or Google sends no refresh token on a second connect.
95
- extraAuthParams: {access_type: 'offline', prompt: 'consent', include_granted_scopes: 'true'},
96
- imap: {host: 'imap.gmail.com', port: 993, secure: true},
97
- smtp: {host: 'smtp.gmail.com', port: 465, secure: true},
98
- smtpPersonal: null,
99
- revokeUrl: 'https://oauth2.googleapis.com/revoke'
100
- }
101
- };
102
-
103
- /** Token-endpoint errors that no retry will clear: the person has to sign in again. */
104
- const PERMANENT = new Set(['invalid_grant', 'invalid_client', 'unauthorized_client', 'interaction_required',
105
- 'consent_required', 'invalid_scope', 'access_denied']);
106
-
107
- /** Swappable for tests - nothing real is reachable from a test run. */
108
- let fetchImpl = (...args) => globalThis.fetch(...args);
109
- /** Told when an account needs reconnecting, and when it is connected again. */
110
- let hooks = {};
111
-
112
- /**
113
- * @param {{fetch?: Function, onNeedsReconnect?: Function, onConnected?: Function}} options
114
- * @returns {void}
115
- */
116
- export function configureOAuth({fetch, onNeedsReconnect, onConnected} = {}) {
117
- if (fetch) fetchImpl = fetch;
118
- if (onNeedsReconnect !== undefined || onConnected !== undefined) {
119
- hooks = {...hooks, ...(onNeedsReconnect !== undefined ? {onNeedsReconnect} : {}),
120
- ...(onConnected !== undefined ? {onConnected} : {})};
121
- }
122
- }
123
-
124
- /** Tests: back to the real network and no listeners. */
125
- export function _resetOAuth() {
126
- fetchImpl = (...args) => globalThis.fetch(...args);
127
- hooks = {};
128
- inFlight.clear();
129
- }
130
-
131
- /**
132
- * A tenant segment for Microsoft's URLs: `common`, `organizations`,
133
- * `consumers` or a tenant id/domain. Anything else falls back to `common`
134
- * rather than being pasted into a URL.
135
- *
136
- * @param {string} value
137
- * @returns {string}
138
- */
139
- export function cleanTenant(value) {
140
- const t = String(value ?? '').trim();
141
- // Dot-separated labels only: no empty label, no `..`, nothing that could
142
- // walk a path segment.
143
- return t.length >= 2 && t.length <= 100 && /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*$/.test(t) ? t : 'common';
144
- }
145
-
146
- /**
147
- * PKCE pair (RFC 7636, S256).
148
- *
149
- * @returns {{verifier: string, challenge: string}}
150
- */
151
- export function pkcePair() {
152
- const verifier = randomBytes(48).toString('base64url');
153
- return {verifier, challenge: createHash('sha256').update(verifier).digest('base64url')};
154
- }
155
-
156
- /**
157
- * The provider's sign-in address. Pure.
158
- *
159
- * @param {{provider: string, clientId: string, tenant?: string, redirectUri: string, state: string,
160
- * codeChallenge?: string, loginHint?: string}} o
161
- * @returns {string}
162
- */
163
- export function authorizeUrl({provider, clientId, tenant, redirectUri, state, codeChallenge, loginHint}) {
164
- const p = PROVIDERS[provider];
165
- if (!p) throw new Error('Unknown provider.');
166
- const q = new URLSearchParams({
167
- client_id: String(clientId ?? '').trim(),
168
- response_type: 'code',
169
- redirect_uri: redirectUri,
170
- scope: p.scopes.join(' '),
171
- state,
172
- ...p.extraAuthParams
173
- });
174
- if (p.pkce && codeChallenge) {
175
- q.set('code_challenge', codeChallenge);
176
- q.set('code_challenge_method', 'S256');
177
- }
178
- if (loginHint) q.set('login_hint', loginHint);
179
- return `${p.authorizeUrl(cleanTenant(tenant))}?${q}`;
180
- }
181
-
182
- /**
183
- * The claims of an id_token. NOT verified: it came straight from the token
184
- * endpoint over TLS in answer to our own request (OpenID Connect Core 3.1.3.7
185
- * allows that), and it is used only to learn the address signed in.
186
- *
187
- * @param {string} idToken
188
- * @returns {object}
189
- */
190
- export function idTokenClaims(idToken) {
191
- try {
192
- const part = String(idToken ?? '').split('.')[1];
193
- return part ? JSON.parse(Buffer.from(part, 'base64url').toString('utf8')) : {};
194
- } catch {
195
- return {};
196
- }
197
- }
198
-
199
- /**
200
- * The mailbox address and outgoing server a token response points at. Pure.
201
- *
202
- * @param {string} provider
203
- * @param {object} claims - idTokenClaims()
204
- * @returns {{email: string, smtp: {host: string, port: number, secure: boolean}}}
205
- */
206
- export function mailboxFor(provider, claims) {
207
- const p = PROVIDERS[provider];
208
- const email = String(claims?.email || claims?.preferred_username || claims?.upn || '').trim().toLowerCase();
209
- const personal = provider === 'microsoft' && claims?.tid === MS_CONSUMER_TENANT;
210
- return {email: /@/.test(email) ? email : '', smtp: personal && p.smtpPersonal ? p.smtpPersonal : p.smtp};
211
- }
212
-
213
- /**
214
- * Does this stored sign-in need renewing before use? Pure.
215
- *
216
- * @param {{expiresAt?: number, accessTokenSealed?: string}} oauth
217
- * @param {number} [now]
218
- * @returns {boolean}
219
- */
220
- export function needsRefresh(oauth, now = Date.now()) {
221
- if (!oauth?.accessTokenSealed) return true;
222
- return !(Number(oauth.expiresAt) > now + REFRESH_SKEW_MS);
223
- }
224
-
225
- /**
226
- * Sort a token endpoint failure into "sign in again" or "try later". Pure.
227
- *
228
- * @param {number} status
229
- * @param {object|null} body
230
- * @returns {{permanent: boolean, code: string, message: string}}
231
- */
232
- export function classifyTokenError(status, body) {
233
- const code = String(body?.error ?? '').trim();
234
- const said = String(body?.error_description ?? '').replace(/[\r\n\t]+/g, ' ').split(/Trace ID:/i)[0].trim().slice(0, 200);
235
- const permanent = PERMANENT.has(code) || (status === 400 && !code) || status === 401;
236
- let message;
237
- if (code === 'invalid_client') message = 'The app\'s client secret was refused - it may have expired. Make a new one, then Reconnect.';
238
- else if (code === 'invalid_grant') message = 'The sign-in has expired or was withdrawn. Reconnect to sign in again.';
239
- else if (permanent) message = `The provider refused to renew the sign-in${said ? `: ${said}` : ''}. Reconnect to sign in again.`;
240
- else message = `The provider could not renew the sign-in just now${said ? ` (${said})` : ` (${status || 'no answer'})`}. It will be tried again.`;
241
- return {permanent, code, message};
242
- }
243
-
244
- /**
245
- * POST a form to a fixed provider endpoint. Redirects are refused (the hosts
246
- * are known; a 3xx is not something to follow with a secret in the body).
247
- *
248
- * @returns {Promise<{status: number, body: object|null}>}
249
- */
250
- async function postForm(url, params) {
251
- const res = await fetchImpl(url, {
252
- method: 'POST',
253
- headers: {'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json'},
254
- body: new URLSearchParams(params).toString(),
255
- redirect: 'manual',
256
- signal: AbortSignal.timeout(20_000)
257
- });
258
- let body = null;
259
- try { body = await res.json(); } catch { body = null; }
260
- return {status: res.status, ok: res.ok, body};
261
- }
262
-
263
- /**
264
- * Trade the code from the callback for tokens.
265
- *
266
- * @param {{provider: string, clientId: string, clientSecret: string, tenant?: string,
267
- * code: string, redirectUri: string, codeVerifier?: string}} o
268
- * @returns {Promise<{accessToken: string, refreshToken: string, expiresAt: number, scope: string, claims: object}>}
269
- */
270
- export async function exchangeCode({provider, clientId, clientSecret, tenant, code, redirectUri, codeVerifier}) {
271
- const p = PROVIDERS[provider];
272
- const params = {client_id: clientId, client_secret: clientSecret, code, redirect_uri: redirectUri, grant_type: 'authorization_code'};
273
- if (p.pkce && codeVerifier) params.code_verifier = codeVerifier;
274
- let r;
275
- try {
276
- r = await postForm(p.tokenUrl(cleanTenant(tenant)), params);
277
- } catch (err) {
278
- throw new Error(`${p.short} could not be reached to finish the sign-in: ${err.message}`);
279
- }
280
- if (!r.ok || !r.body?.access_token) {
281
- const why = classifyTokenError(r.status, r.body);
282
- throw new Error(`${p.short} refused the sign-in${why.code ? ` (${why.code})` : ''}: ${String(r.body?.error_description || r.status).split(/Trace ID:/i)[0].trim().slice(0, 200)}`);
283
- }
284
- if (!r.body.refresh_token) {
285
- throw new Error(provider === 'google'
286
- ? 'Google sent no refresh token. Remove the app from your Google account\'s third-party access, then Connect again.'
287
- : 'Microsoft sent no refresh token - is offline_access among the app\'s API permissions?');
288
- }
289
- if (provider === 'google' && r.body.scope && !String(r.body.scope).split(' ').includes('https://mail.google.com/')) {
290
- throw new Error('Mail access was not granted - tick it on Google\'s consent screen, then Connect again.');
291
- }
292
- return {
293
- accessToken: r.body.access_token,
294
- refreshToken: r.body.refresh_token,
295
- expiresAt: Date.now() + (Number(r.body.expires_in) || 3600) * 1000,
296
- scope: String(r.body.scope ?? ''),
297
- claims: idTokenClaims(r.body.id_token)
298
- };
299
- }
300
-
301
- /** One refresh per account at a time - a rotated refresh token must not be spent twice. */
302
- const inFlight = new Map();
303
-
304
- /**
305
- * Renew an account's access token (or hand back the stored one while it is
306
- * still good, unless `force`). Saves the new token, and a rotated refresh
307
- * token. Throws OAuthReconnectError when the provider refuses for good (the
308
- * account is marked and its owner told), a plain Error when it merely failed.
309
- *
310
- * @param {string} userId
311
- * @param {string} accountId
312
- * @param {{force?: boolean}} [options]
313
- * @returns {Promise<{accessToken: string, expiresAt: number, account: object}>}
314
- */
315
- export function refreshAccount(userId, accountId, {force = false} = {}) {
316
- const key = `${userId}:${accountId}`;
317
- const running = inFlight.get(key);
318
- if (running) return running;
319
- const job = doRefresh(userId, accountId, force).finally(() => inFlight.delete(key));
320
- inFlight.set(key, job);
321
- return job;
322
- }
323
-
324
- async function doRefresh(userId, accountId, force) {
325
- // Always the stored record: another caller may have rotated the token since
326
- // this account object was read.
327
- const account = await accounts.getAccount(userId, accountId);
328
- if (!account || !accounts.isOAuth(account)) throw new Error('That mailbox is not signed in with a provider.');
329
- if (accounts.needsReconnect(account)) throw new OAuthReconnectError(account.oauth?.error || undefined);
330
- const o = account.oauth;
331
- if (!force && !needsRefresh(o)) {
332
- return {accessToken: open(o.accessTokenSealed), expiresAt: Number(o.expiresAt), account};
333
- }
334
-
335
- const p = PROVIDERS[o.provider];
336
- // The generation this renewal works against - see updateOAuth.
337
- const gen = Number(o.gen) || 0;
338
- let clientSecret;
339
- let refreshToken;
340
- try {
341
- clientSecret = open(o.clientSecretSealed);
342
- refreshToken = open(o.refreshTokenSealed);
343
- } catch (err) {
344
- // The key moved (MAIL_SECRET added, say): nothing to refresh with.
345
- return markBroken(account, err.message);
346
- }
347
-
348
- const params = {client_id: o.clientId, client_secret: clientSecret, refresh_token: refreshToken, grant_type: 'refresh_token'};
349
- if (p.refreshScope) params.scope = p.refreshScope;
350
- let r;
351
- try {
352
- r = await postForm(p.tokenUrl(cleanTenant(o.tenant)), params);
353
- } catch (err) {
354
- throw new Error(`${p.short} could not be reached to renew the sign-in: ${err.message}`);
355
- }
356
- if (!r.ok || !r.body?.access_token) {
357
- const why = classifyTokenError(r.status, r.body);
358
- if (why.permanent) return markBroken(account, why.message);
359
- throw new Error(why.message);
360
- }
361
-
362
- const expiresAt = Date.now() + (Number(r.body.expires_in) || 3600) * 1000;
363
- const saved = await accounts.updateOAuth(userId, accountId, {
364
- accessTokenSealed: seal(r.body.access_token),
365
- expiresAt,
366
- // Rotation: Microsoft answers a new one and the old must be discarded.
367
- ...(r.body.refresh_token && r.body.refresh_token !== refreshToken ? {refreshTokenSealed: seal(r.body.refresh_token)} : {}),
368
- refreshedAt: new Date().toISOString(),
369
- error: null
370
- }, {expectGen: gen, requireOk: true});
371
- if (!saved) {
372
- // Reconnected or Disconnected while this renewal was on the wire: the
373
- // stored state is newer and wins. Answer from it, never over it.
374
- const now = await accounts.getAccount(userId, accountId);
375
- if (!now || accounts.needsReconnect(now)) throw new OAuthReconnectError(now?.oauth?.error || undefined);
376
- try {
377
- return {accessToken: open(now.oauth.accessTokenSealed), expiresAt: Number(now.oauth.expiresAt), account: now};
378
- } catch {
379
- throw new Error('The sign-in changed while it was being renewed. Try again.');
380
- }
381
- }
382
- return {accessToken: r.body.access_token, expiresAt, account: saved};
383
- }
384
-
385
- /** Mark an account as needing a new sign-in, tell its owner, and throw. */
386
- async function markBroken(account, message) {
387
- const wasOk = account.oauth?.status === 'ok';
388
- // Only the sign-in that was refused: a fresh one made meanwhile (Reconnect)
389
- // is a different generation and must not be marked broken by the old one.
390
- const saved = await accounts.updateOAuth(account.userId, account.id,
391
- {status: 'reconnect', error: message, accessTokenSealed: null},
392
- {expectGen: Number(account.oauth?.gen) || 0});
393
- if (!saved) throw new Error('The sign-in changed while it was being renewed. Try again.');
394
- if (wasOk) {
395
- try { hooks.onNeedsReconnect?.(saved ?? account, message); } catch { /* a notice never breaks mail */ }
396
- }
397
- throw new OAuthReconnectError(message);
398
- }
399
-
400
- /**
401
- * The function `toConnection()` hangs on a connection: renew (or force a
402
- * renewal) and answer the new auth for that protocol.
403
- *
404
- * @param {object} account
405
- * @returns {(force: boolean) => Promise<{accessToken: string, expiresAt: number}>}
406
- */
407
- export function refresherFor(account) {
408
- return async (force = false) => {
409
- const r = await refreshAccount(account.userId, account.id, {force});
410
- return {accessToken: r.accessToken, expiresAt: r.expiresAt};
411
- };
412
- }
413
-
414
- /**
415
- * Hand the refresh token back to the provider, where it can be (Google).
416
- * Best-effort: a sign-in we forget is gone from here either way.
417
- *
418
- * @param {object} account
419
- * @returns {Promise<{revoked: boolean, supported: boolean}>}
420
- */
421
- export async function revokeAccount(account) {
422
- const p = PROVIDERS[account?.oauth?.provider];
423
- if (!p?.revokeUrl) return {revoked: false, supported: false};
424
- let token;
425
- try {
426
- token = open(account.oauth.refreshTokenSealed);
427
- } catch {
428
- return {revoked: false, supported: true};
429
- }
430
- try {
431
- const r = await postForm(p.revokeUrl, {token});
432
- return {revoked: r.ok, supported: true};
433
- } catch {
434
- return {revoked: false, supported: true};
435
- }
436
- }
437
-
438
- /** Tell the listener an account is connected again (the callback). */
439
- export function announceConnected(account) {
440
- try { hooks.onConnected?.(account); } catch { /* ditto */ }
441
- }
442
-
443
- /**
444
- * What the admin is told about the providers - no secrets.
445
- *
446
- * @returns {object[]}
447
- */
448
- export function describeProviders() {
449
- return Object.values(PROVIDERS).map(p => ({
450
- id: p.id, label: p.label, short: p.short, needsTenant: p.needsTenant,
451
- imap: p.imap, smtp: p.smtp, scopes: p.scopes, canRevoke: Boolean(p.revokeUrl)
452
- }));
453
- }
3
+ import * as secrets from './secretbox.js';
4
+ import {createOAuth} from './oauthRuntime.js';
5
+ export const {REFRESH_SKEW_MS, PROVIDERS, configureOAuth, _resetOAuth, cleanTenant, pkcePair, authorizeUrl, idTokenClaims, mailboxFor, needsRefresh, classifyTokenError, exchangeCode, refreshAccount, refresherFor, revokeAccount, announceConnected, describeProviders} = createOAuth({accounts, secrets, OAuthReconnectError});