@wtfalch/email 0.7.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.
@@ -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
- * **`Inherit`, not a narrower set, and that is a finding rather than a
167
- * shortcut.** `permissions` does take a `{'@type':'Replace', permissions:
168
- * {…}}` form, and an empty one really does restrict — such a key is
169
- * `forbidden` on every management method. But of some sixty candidate
170
- * permission names tried against 0.16.20 on 2026-09-07, only
171
- * `authenticate` and `impersonate` were accepted, and a key holding both
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
- * The key is therefore as powerful as the account it belongs to — the same
178
- * power as its app password — and what it buys is not least privilege but
179
- * two other things: it is typed `ApiKey`, which the `/email` section's revoke
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: { '@type': 'Inherit' } } },
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/mail`, and the two are kept apart on purpose: this
10
- * one runs on a server holding a credential that, on 0.16, cannot be scoped
11
- * and is as powerful as the account it belongs to, and that must never be
12
- * one import away from something a browser bundles.
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';
@@ -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/mail`, and the two are kept apart on purpose: this
10
- * one runs on a server holding a credential that, on 0.16, cannot be scoped
11
- * and is as powerful as the account it belongs to, and that must never be
12
- * one import away from something a browser bundles.
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.7.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",