@wtfalch/email 0.8.0 → 0.9.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.
|
@@ -2,9 +2,11 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* What a browser bundle gets instead of the administration client.
|
|
4
4
|
*
|
|
5
|
-
* This entry reaches a mail server with an
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* This entry reaches a mail server with an administrative credential. A
|
|
6
|
+
* minted API key can be scoped — `DASHBOARD_PERMISSIONS` is the set a
|
|
7
|
+
* dashboard needs — but nothing obliges a caller to pass a scoped one, and an
|
|
8
|
+
* account password or an `'inherit'` key is as powerful as the whole account.
|
|
9
|
+
* It must never end up in something a browser downloads.
|
|
8
10
|
*
|
|
9
11
|
* **Why the `browser` condition and not `server-only`.** `server-only` throws
|
|
10
12
|
* in any environment without React's `react-server` condition, which includes
|
|
@@ -34,6 +34,22 @@ export type StalwartAuth = {
|
|
|
34
34
|
};
|
|
35
35
|
/** API-key secrets are `API_`-prefixed on 0.16, which is how a caller can tell one from an app password. */
|
|
36
36
|
export declare const API_KEY_PREFIX = "API_";
|
|
37
|
+
/**
|
|
38
|
+
* What a dashboard's mail section needs and nothing more, verified against
|
|
39
|
+
* 0.16.20 on 2026-09-14. This is the default {@link StalwartClient.createApiKey}
|
|
40
|
+
* mints.
|
|
41
|
+
*
|
|
42
|
+
* It covers `loadOverview`, `createMailbox`, `addAlias`, `removeAlias` and
|
|
43
|
+
* `revokeAppPassword` — the five operations the `/email` pages perform. A key
|
|
44
|
+
* holding exactly these is `forbidden` on `Email/query` for every account on
|
|
45
|
+
* the instance, its own included, so it administers mail without being able
|
|
46
|
+
* to read any.
|
|
47
|
+
*
|
|
48
|
+
* `authenticate` is what lets the key be presented at all; the `sys*` names
|
|
49
|
+
* are Stalwart's management vocabulary (`enums.Permission`), which is why the
|
|
50
|
+
* earlier guessed names all failed.
|
|
51
|
+
*/
|
|
52
|
+
export declare const DASHBOARD_PERMISSIONS: readonly ["authenticate", "sysAccountQuery", "sysAccountGet", "sysAccountCreate", "sysAccountUpdate", "sysDomainQuery", "sysDomainGet", "sysSystemSettingsGet"];
|
|
37
53
|
/** Which scheme a secret wants, from its own shape, for a caller holding one opaque string. */
|
|
38
54
|
export declare function authFor(secret: string, user?: string): StalwartAuth;
|
|
39
55
|
export declare class StalwartError extends Error {
|
|
@@ -70,24 +86,28 @@ export declare class StalwartClient {
|
|
|
70
86
|
* Mint an API key for the authenticated account through the self-service
|
|
71
87
|
* API, and return its secret, which is in the response and nowhere else.
|
|
72
88
|
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
* `
|
|
77
|
-
*
|
|
78
|
-
* `
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
*
|
|
89
|
+
* **Scoped by default, because a scoped key does work.** An earlier reading
|
|
90
|
+
* of this API concluded that `Inherit` was the only usable value, from some
|
|
91
|
+
* sixty guessed permission names of which only `authenticate` and
|
|
92
|
+
* `impersonate` were accepted. The guesses were the problem: the vocabulary
|
|
93
|
+
* is `enums.Permission`, and its management names are
|
|
94
|
+
* `sys<Object><Verb>` — `sysAccountQuery`, `sysDomainGet` and so on.
|
|
95
|
+
*
|
|
96
|
+
* {@link DASHBOARD_PERMISSIONS} is the set verified against 0.16.20 on
|
|
97
|
+
* 2026-09-14. A key holding it answers `x:Account/query|get|set`,
|
|
98
|
+
* `x:Domain/query|get` and `x:SystemSettings/get`, which is everything a
|
|
99
|
+
* dashboard's mail section does, and is `forbidden` on `Email/query` for
|
|
100
|
+
* every account including its own. It cannot read anyone's mail.
|
|
101
|
+
*
|
|
102
|
+
* Pass an explicit set to widen or narrow it, or `'inherit'` for a key as
|
|
103
|
+
* powerful as the account itself. Prefer a set: `'inherit'` hands the
|
|
104
|
+
* holder every mailbox on the instance.
|
|
83
105
|
*
|
|
84
|
-
*
|
|
85
|
-
* power as its app password — and what it buys is not least privilege but
|
|
86
|
-
* two other things: it is typed `ApiKey`, which the `/email` section's revoke
|
|
106
|
+
* Either way the key is typed `ApiKey`, which the `/email` section's revoke
|
|
87
107
|
* refuses to touch, and it goes as Bearer, so it carries no account name
|
|
88
108
|
* and cannot be used to sign in to mail as a person.
|
|
89
109
|
*/
|
|
90
|
-
createApiKey(description: string): Promise<string>;
|
|
110
|
+
createApiKey(description: string, permissions?: readonly string[] | 'inherit'): Promise<string>;
|
|
91
111
|
/**
|
|
92
112
|
* Mint an app password for the authenticated account through the
|
|
93
113
|
* self-service API. The secret is in the response and nowhere else. An app
|
|
@@ -24,6 +24,31 @@
|
|
|
24
24
|
const USING = ['urn:ietf:params:jmap:core', 'urn:stalwart:jmap'];
|
|
25
25
|
/** API-key secrets are `API_`-prefixed on 0.16, which is how a caller can tell one from an app password. */
|
|
26
26
|
export const API_KEY_PREFIX = 'API_';
|
|
27
|
+
/**
|
|
28
|
+
* What a dashboard's mail section needs and nothing more, verified against
|
|
29
|
+
* 0.16.20 on 2026-09-14. This is the default {@link StalwartClient.createApiKey}
|
|
30
|
+
* mints.
|
|
31
|
+
*
|
|
32
|
+
* It covers `loadOverview`, `createMailbox`, `addAlias`, `removeAlias` and
|
|
33
|
+
* `revokeAppPassword` — the five operations the `/email` pages perform. A key
|
|
34
|
+
* holding exactly these is `forbidden` on `Email/query` for every account on
|
|
35
|
+
* the instance, its own included, so it administers mail without being able
|
|
36
|
+
* to read any.
|
|
37
|
+
*
|
|
38
|
+
* `authenticate` is what lets the key be presented at all; the `sys*` names
|
|
39
|
+
* are Stalwart's management vocabulary (`enums.Permission`), which is why the
|
|
40
|
+
* earlier guessed names all failed.
|
|
41
|
+
*/
|
|
42
|
+
export const DASHBOARD_PERMISSIONS = [
|
|
43
|
+
'authenticate',
|
|
44
|
+
'sysAccountQuery',
|
|
45
|
+
'sysAccountGet',
|
|
46
|
+
'sysAccountCreate',
|
|
47
|
+
'sysAccountUpdate',
|
|
48
|
+
'sysDomainQuery',
|
|
49
|
+
'sysDomainGet',
|
|
50
|
+
'sysSystemSettingsGet',
|
|
51
|
+
];
|
|
27
52
|
/** Which scheme a secret wants, from its own shape, for a caller holding one opaque string. */
|
|
28
53
|
export function authFor(secret, user) {
|
|
29
54
|
if (secret.startsWith(API_KEY_PREFIX))
|
|
@@ -163,26 +188,36 @@ export class StalwartClient {
|
|
|
163
188
|
* Mint an API key for the authenticated account through the self-service
|
|
164
189
|
* API, and return its secret, which is in the response and nowhere else.
|
|
165
190
|
*
|
|
166
|
-
*
|
|
167
|
-
*
|
|
168
|
-
*
|
|
169
|
-
* `
|
|
170
|
-
*
|
|
171
|
-
* `
|
|
172
|
-
* is still `forbidden` on `x:Account/query`, `x:Domain/query`,
|
|
173
|
-
* `x:SystemSettings/get` and `x:ApiKey/query`. There is no name in this
|
|
174
|
-
* API's vocabulary that grants management access, so a scoped key cannot
|
|
175
|
-
* manage principals at all. `Inherit` is the only value that works.
|
|
191
|
+
* **Scoped by default, because a scoped key does work.** An earlier reading
|
|
192
|
+
* of this API concluded that `Inherit` was the only usable value, from some
|
|
193
|
+
* sixty guessed permission names of which only `authenticate` and
|
|
194
|
+
* `impersonate` were accepted. The guesses were the problem: the vocabulary
|
|
195
|
+
* is `enums.Permission`, and its management names are
|
|
196
|
+
* `sys<Object><Verb>` — `sysAccountQuery`, `sysDomainGet` and so on.
|
|
176
197
|
*
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
198
|
+
* {@link DASHBOARD_PERMISSIONS} is the set verified against 0.16.20 on
|
|
199
|
+
* 2026-09-14. A key holding it answers `x:Account/query|get|set`,
|
|
200
|
+
* `x:Domain/query|get` and `x:SystemSettings/get`, which is everything a
|
|
201
|
+
* dashboard's mail section does, and is `forbidden` on `Email/query` for
|
|
202
|
+
* every account including its own. It cannot read anyone's mail.
|
|
203
|
+
*
|
|
204
|
+
* Pass an explicit set to widen or narrow it, or `'inherit'` for a key as
|
|
205
|
+
* powerful as the account itself. Prefer a set: `'inherit'` hands the
|
|
206
|
+
* holder every mailbox on the instance.
|
|
207
|
+
*
|
|
208
|
+
* Either way the key is typed `ApiKey`, which the `/email` section's revoke
|
|
180
209
|
* refuses to touch, and it goes as Bearer, so it carries no account name
|
|
181
210
|
* and cannot be used to sign in to mail as a person.
|
|
182
211
|
*/
|
|
183
|
-
async createApiKey(description) {
|
|
212
|
+
async createApiKey(description, permissions = DASHBOARD_PERMISSIONS) {
|
|
213
|
+
const scope = permissions === 'inherit'
|
|
214
|
+
? { '@type': 'Inherit' }
|
|
215
|
+
: {
|
|
216
|
+
'@type': 'Replace',
|
|
217
|
+
permissions: Object.fromEntries(permissions.map((p) => [p, true])),
|
|
218
|
+
};
|
|
184
219
|
const res = await this.call('x:ApiKey/set', {
|
|
185
|
-
create: { new: { description, permissions:
|
|
220
|
+
create: { new: { description, permissions: scope } },
|
|
186
221
|
});
|
|
187
222
|
const failure = res.notCreated?.new;
|
|
188
223
|
if (failure)
|
|
@@ -6,15 +6,15 @@
|
|
|
6
6
|
* **Not a JMAP mail client.** This speaks the `urn:stalwart:jmap` management
|
|
7
7
|
* extension — `x:Account`, `x:Domain`, `x:ApiKey` and their neighbours —
|
|
8
8
|
* which is a different surface from RFC 8620 and 8621. Reading and writing
|
|
9
|
-
* messages is `@wtfalch/
|
|
10
|
-
* one runs on a server holding
|
|
11
|
-
*
|
|
12
|
-
*
|
|
9
|
+
* messages is `@wtfalch/email/mailbox`, and the two are kept apart on
|
|
10
|
+
* purpose: this one runs on a server holding an administrative credential,
|
|
11
|
+
* which a caller may or may not have scoped, and that must never be one
|
|
12
|
+
* import away from something a browser bundles.
|
|
13
13
|
*
|
|
14
14
|
* The main entry is pure Node so a provisioning script can use it. The
|
|
15
15
|
* components live behind `@wtfalch/postmaster/react`.
|
|
16
16
|
*/
|
|
17
|
-
export { API_KEY_PREFIX, StalwartClient, StalwartError, authFor, type Credential, type StalwartAuth, } from './client.js';
|
|
17
|
+
export { API_KEY_PREFIX, DASHBOARD_PERMISSIONS, StalwartClient, StalwartError, authFor, type Credential, type StalwartAuth, } from './client.js';
|
|
18
18
|
export { type Instance, openInstance } from './instance.js';
|
|
19
19
|
export { loadOverview } from './load.js';
|
|
20
20
|
export { applyObjects, mailObjects, ref, type MailObjectsInput, type PlannedObject, } from './objects.js';
|
package/dist/postmaster/index.js
CHANGED
|
@@ -6,15 +6,15 @@
|
|
|
6
6
|
* **Not a JMAP mail client.** This speaks the `urn:stalwart:jmap` management
|
|
7
7
|
* extension — `x:Account`, `x:Domain`, `x:ApiKey` and their neighbours —
|
|
8
8
|
* which is a different surface from RFC 8620 and 8621. Reading and writing
|
|
9
|
-
* messages is `@wtfalch/
|
|
10
|
-
* one runs on a server holding
|
|
11
|
-
*
|
|
12
|
-
*
|
|
9
|
+
* messages is `@wtfalch/email/mailbox`, and the two are kept apart on
|
|
10
|
+
* purpose: this one runs on a server holding an administrative credential,
|
|
11
|
+
* which a caller may or may not have scoped, and that must never be one
|
|
12
|
+
* import away from something a browser bundles.
|
|
13
13
|
*
|
|
14
14
|
* The main entry is pure Node so a provisioning script can use it. The
|
|
15
15
|
* components live behind `@wtfalch/postmaster/react`.
|
|
16
16
|
*/
|
|
17
|
-
export { API_KEY_PREFIX, StalwartClient, StalwartError, authFor, } from './client.js';
|
|
17
|
+
export { API_KEY_PREFIX, DASHBOARD_PERMISSIONS, StalwartClient, StalwartError, authFor, } from './client.js';
|
|
18
18
|
export { openInstance } from './instance.js';
|
|
19
19
|
export { loadOverview } from './load.js';
|
|
20
20
|
export { applyObjects, mailObjects, ref, } from './objects.js';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wtfalch/email",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "The wtfalch estate: reading a mailbox over JMAP, and administering the Stalwart server it lives on. Two entries with no code in common.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|