@wtfalch/postmaster 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Tallis Falch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/apply.d.ts

@@ -0,0 +1,61 @@
+import type { Instance } from './instance.js';
+export interface Applied {
+    /** For the audit row's `targetType`. */
+    readonly targetType: 'mailbox' | 'mail_alias' | 'mail_app_password';
+    /** For its `targetId`: the address or the credential, never a secret. */
+    readonly targetId: string;
+    readonly before: unknown;
+    readonly after: unknown;
+    /** What to tell the person who pressed the button. */
+    readonly message: string;
+}
+/**
+ * Give a person a mailbox. The address is checked against the server rather
+ * than against the page: two admins pressing "create" for the same person at
+ * once would otherwise make two accounts, and the second would be the one
+ * mail stopped arriving at.
+ */
+export declare function createMailbox(instance: Instance, input: {
+    local: string;
+    domainId: string;
+    apex: string;
+    description?: string | null;
+    external: boolean;
+}): Promise<Applied>;
+export declare function addAlias(instance: Instance, input: {
+    accountId: string;
+    name: string;
+    domainId: string;
+    apex: string;
+}): Promise<Applied>;
+export declare function removeAlias(instance: Instance, input: {
+    accountId: string;
+    name: string;
+    domainId: string;
+    apex: string;
+}): Promise<Applied>;
+/**
+ * Stop one app password working. The secret is never read, here or anywhere
+ * else: the entry is identified by its id and the surviving entries go back
+ * with the masked secrets the server sent, which it reads as "leave these
+ * alone".
+ *
+ * **Never on the account this management app signs in as.** `withoutAppPassword`
+ * refuses an `ApiKey`, which is what D3's credential is once `mail-configure`
+ * has minted one — but an instance configured with an *app password* on the
+ * administrator instead (a laptop, or an instance provisioned before slice 3)
+ * holds a credential that guard cannot tell from a person's phone.
+ * The administrator is on the default domain, so the page lists it with a
+ * revoke button beside every app password it has, one of which is the one
+ * serving the request. Pressing it would answer "that app password no
+ * longer works" and then fail every subsequent request with `unauthorized`
+ * until somebody edits the Coolify environment. So the whole account is off
+ * limits here; its credentials belong to the bootstrap and to this app,
+ * never to a mail client, and the web admin is where they are managed.
+ */
+export declare function revokeAppPassword(instance: Instance, input: {
+    accountId: string;
+    credentialId: string;
+    domainId: string;
+    apex: string;
+}): Promise<Applied>;

package/dist/apply.js

@@ -0,0 +1,191 @@
+import { MailWriteRefused, newAccount, withAlias, withoutAlias, withoutAppPassword, } from './writes.js';
+/**
+ * The four writes `/email` makes, each as one round trip against the mail
+ * instance's management API.
+ *
+ * **Every one re-reads the account first, and none trusts the page.** A
+ * `List<T>` write replaces the whole list, so computing the new list from
+ * what the browser last rendered would delete anything added since — an
+ * alias a colleague added a minute ago, an app password somebody minted on
+ * their phone. The page supplies only what to change (an account id, an
+ * alias name, a credential id); what it is changed *from* is read here, on
+ * this request. That is also why the refusals in `./writes.ts` are worth
+ * having: with a fresh read, "this mailbox has no alias x" means the alias
+ * is really gone, not that the page was stale.
+ *
+ * **What that read does not close is a same-instant race, and it cannot be
+ * closed here.** Two writes to one mailbox's list that overlap between the
+ * read and the write will still lose one, because the second `/set` replaces
+ * the list the first wrote. JMAP's answer is `ifInState`, and Stalwart 0.16
+ * does not offer it: `x:Account/get` returns `accountId`, `list` and
+ * `notFound` with no state token, and `x:Account/set` rejects an `ifInState`
+ * argument outright as `notRequest` (checked 2026-09-07). There is nothing
+ * to be conditional on.
+ *
+ * So the write cannot be made safe, and what happens instead is that it is
+ * made *loud*: `confirmSurvivors` re-reads after every list write and says so
+ * when something the caller never touched has gone. That does not undo the
+ * loss — nothing here can — but it turns a silent deletion into a sentence
+ * naming what disappeared, which is the difference between finding out now
+ * and finding out when somebody's mail stops arriving.
+ *
+ * **Every account is checked against the domain the caller resolved.** The
+ * credential this app holds is the instance administrator's, so it
+ * reaches every account on every domain the instance serves — and instance
+ * one serves two. The account id arrives from the browser, so without this
+ * check a `mail:admin` could name an account the page never showed them,
+ * on a domain this app does not manage, and the audit row would name
+ * an address on the wrong domain because it is composed from the resolved
+ * apex.
+ *
+ * Each returns the `before`/`after` pair an audit row records, as plain
+ * JSON, plus a sentence for the person who pressed the button.
+ */
+/**
+ * After a list write, whether everything the caller meant to keep is still
+ * there. Compared by name rather than by deep equality: the server
+ * normalises what it stores, and a false alarm on every write would train
+ * the reader to ignore a true one.
+ *
+ * Returns a sentence to append when something is missing, and `''` when all
+ * is well.
+ */
+function missingSince(expected, actual) {
+    const gone = expected.filter((name) => !actual.includes(name));
+    if (gone.length === 0)
+        return '';
+    return ` Note: ${gone.join(', ')} ${gone.length === 1 ? 'was' : 'were'} also on this mailbox a moment ago and ${gone.length === 1 ? 'is' : 'are'} not now — somebody else was editing it at the same time, and this write replaced what they had just set. Check the mailbox before relying on it.`;
+}
+/** The alias names on an account, as the server has them right now. */
+async function aliasNames(instance, accountId) {
+    const [fresh] = await instance.client.get('Account', [accountId]);
+    return Object.values(fresh?.aliases ?? {}).map((a) => a.name);
+}
+/** The credential ids on an account, as the server has them right now. */
+async function credentialIds(instance, accountId) {
+    const [fresh] = await instance.client.get('Account', [accountId]);
+    return Object.values(fresh?.credentials ?? {})
+        .map((c) => c.credentialId)
+        .filter((id) => typeof id === 'string');
+}
+/**
+ * The account as the server has it right now, confined to the domain the
+ * caller resolved. A mismatched domain gets the same answer as a missing
+ * account, deliberately: telling a caller "that exists, but not here" turns
+ * the id into an oracle for every mailbox on the instance.
+ */
+async function readAccount(instance, accountId, domainId) {
+    const [account] = await instance.client.get('Account', [accountId]);
+    if (!account || account.domainId !== domainId) {
+        throw new MailWriteRefused('that mailbox is not on this domain any more');
+    }
+    return account;
+}
+/**
+ * Whether this account is the one this app itself signs in as.
+ *
+ * `MAIL_ADMIN_USER` is a whole address and an account's `name` is a local
+ * part, so the comparison is made on the address. Used to keep this app
+ * from revoking its own credential (see `revokeAppPassword`).
+ */
+function isOurOwnAccount(instance, account, apex) {
+    // With an API key there is no account to compare: a Bearer credential
+    // carries no account name, and `withoutAppPassword`'s refusal to touch an
+    // `ApiKey` is what keeps this app from revoking itself. The comparison
+    // matters on the app-password path, where the credential is an app
+    // password on the administrator and indistinguishable from a person's.
+    if (instance.user === null)
+        return false;
+    return `${account.name}@${apex}`.toLowerCase() === instance.user.toLowerCase();
+}
+/**
+ * Give a person a mailbox. The address is checked against the server rather
+ * than against the page: two admins pressing "create" for the same person at
+ * once would otherwise make two accounts, and the second would be the one
+ * mail stopped arriving at.
+ */
+export async function createMailbox(instance, input) {
+    // Throws before any read when the request is one this app does not make
+    // (a whole address, an empty name, a domain that keeps its own passwords).
+    const value = newAccount(input);
+    const local = value.name;
+    const address = `${local}@${input.apex}`;
+    const existing = (await instance.client.list('Account')).find((a) => a.domainId === input.domainId && a.name.toLowerCase() === local);
+    if (existing) {
+        throw new MailWriteRefused(`${address} already has a mailbox`);
+    }
+    const id = await instance.client.create('Account', value);
+    return {
+        targetType: 'mailbox',
+        targetId: address,
+        before: null,
+        after: { id, name: local, domainId: input.domainId, description: input.description ?? null },
+        message: `${address} now has a mailbox. They sign in through the issuer and make an app password for their mail client.`,
+    };
+}
+export async function addAlias(instance, input) {
+    const account = await readAccount(instance, input.accountId, input.domainId);
+    const aliases = withAlias(account, { name: input.name, domainId: input.domainId });
+    await instance.client.update('Account', account.id, { aliases });
+    const added = Object.values(aliases).at(-1)?.name;
+    const lost = missingSince(Object.values(aliases).map((a) => a.name), await aliasNames(instance, account.id));
+    return {
+        targetType: 'mail_alias',
+        targetId: `${added}@${input.apex}`,
+        before: null,
+        after: { alias: added, mailbox: `${account.name}@${input.apex}` },
+        message: `${added}@${input.apex} is now delivered to ${account.name}@${input.apex}.${lost}`,
+    };
+}
+export async function removeAlias(instance, input) {
+    const account = await readAccount(instance, input.accountId, input.domainId);
+    const aliases = withoutAlias(account, input.name);
+    await instance.client.update('Account', account.id, { aliases });
+    const lost = missingSince(Object.values(aliases).map((a) => a.name), await aliasNames(instance, account.id));
+    return {
+        targetType: 'mail_alias',
+        targetId: `${input.name}@${input.apex}`,
+        before: { alias: input.name, mailbox: `${account.name}@${input.apex}` },
+        after: null,
+        message: `${input.name}@${input.apex} is no longer delivered anywhere. Mail sent to it will be rejected.${lost}`,
+    };
+}
+/**
+ * Stop one app password working. The secret is never read, here or anywhere
+ * else: the entry is identified by its id and the surviving entries go back
+ * with the masked secrets the server sent, which it reads as "leave these
+ * alone".
+ *
+ * **Never on the account this management app signs in as.** `withoutAppPassword`
+ * refuses an `ApiKey`, which is what D3's credential is once `mail-configure`
+ * has minted one — but an instance configured with an *app password* on the
+ * administrator instead (a laptop, or an instance provisioned before slice 3)
+ * holds a credential that guard cannot tell from a person's phone.
+ * The administrator is on the default domain, so the page lists it with a
+ * revoke button beside every app password it has, one of which is the one
+ * serving the request. Pressing it would answer "that app password no
+ * longer works" and then fail every subsequent request with `unauthorized`
+ * until somebody edits the Coolify environment. So the whole account is off
+ * limits here; its credentials belong to the bootstrap and to this app,
+ * never to a mail client, and the web admin is where they are managed.
+ */
+export async function revokeAppPassword(instance, input) {
+    const account = await readAccount(instance, input.accountId, input.domainId);
+    if (isOurOwnAccount(instance, account, input.apex)) {
+        throw new MailWriteRefused(`${instance.user} is the account this management app signs in as, and one of its app passwords is serving this request. Manage its credentials in the web admin.`);
+    }
+    const before = Object.values(account.credentials ?? {}).find((c) => c.credentialId === input.credentialId);
+    const credentials = withoutAppPassword(account, input.credentialId);
+    await instance.client.update('Account', account.id, { credentials });
+    const description = typeof before?.description === 'string' ? before.description : null;
+    const lost = missingSince(Object.values(credentials)
+        .map((c) => c.credentialId)
+        .filter((id) => typeof id === 'string'), await credentialIds(instance, account.id));
+    return {
+        targetType: 'mail_app_password',
+        targetId: input.credentialId,
+        before: { mailbox: `${account.name}@${input.apex}`, description },
+        after: null,
+        message: `That app password no longer works${description ? ` (${description})` : ''}. Any mail client using it will be asked to sign in again.${lost}`,
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Minimal client for Stalwart's management API, which is JMAP: every
+ * configuration object (Domain, AcmeProvider, MtaRoute, SystemSettings, …) is
+ * read and written with `x:<Object>/get|query|set` under the
+ * `urn:stalwart:jmap` capability. There is no REST surface for these in 0.16;
+ * the web admin and `stalwart-cli` speak exactly this.
+ *
+ * Shapes that differ from the docs and were confirmed on 0.16.20 (see
+ * docs/plans/email/phase-1-runbook.md, "What happened"):
+ *   - a `List<T>` field is a map keyed by index: `{"0": …}`, never an array;
+ *   - a `Map<T>` / `Set<T>` field is `{"value": true}`;
+ *   - a `SecretKey` from the environment is
+ *     `{"@type":"EnvironmentVariable","variableName":"…"}`;
+ *   - singletons are addressed with the id `singleton`.
+ *
+ * Authentication is Basic for a password or an app password, and **Bearer
+ * for an API key** — confirmed on 0.16.20, 2026-09-07: an `ApiKey` secret
+ * presented as Basic is refused with 401 whatever username accompanies it,
+ * and the same secret as `Authorization: Bearer` is accepted. That is why
+ * `StalwartAuth` is a union rather than a pair of strings. Until
+ * `Bootstrap/set` has run, the only account is the recovery admin from
+ * `STALWART_RECOVERY_ADMIN`; after it, the administrator it generated.
+ */
+/**
+ * How to authenticate. An account's password or app password goes as Basic
+ * with the account name beside it; an API key goes as Bearer and carries no
+ * account name at all, which is why `apiKey` is alone in its variant.
+ */
+export type StalwartAuth = {
+    user: string;
+    password: string;
+} | {
+    apiKey: string;
+};
+/** API-key secrets are `API_`-prefixed on 0.16, which is how a caller can tell one from an app password. */
+export declare const API_KEY_PREFIX = "API_";
+/** Which scheme a secret wants, from its own shape, for a caller holding one opaque string. */
+export declare function authFor(secret: string, user?: string): StalwartAuth;
+export declare class StalwartError extends Error {
+    readonly method: string;
+    readonly type: string;
+    constructor(method: string, type: string, description?: string);
+}
+export declare class StalwartClient {
+    #private;
+    private base;
+    /** @param baseUrl e.g. `https://email.example.com`, no trailing slash needed. */
+    constructor(baseUrl: string, auth: StalwartAuth);
+    private headers;
+    /** One method call; throws `StalwartError` on a JMAP-level error. */
+    call<T = Record<string, unknown>>(method: string, args: Record<string, unknown>): Promise<T>;
+    /**
+     * Whether the server answers at all, and whether it is still in bootstrap
+     * mode. In bootstrap mode JMAP accepts only the `Bootstrap` object, so a
+     * `SystemSettings/get` is refused; that refusal is the signal.
+     */
+    probe(): Promise<'down' | 'bootstrap' | 'ready'>;
+    waitFor(state: 'bootstrap' | 'ready', timeoutMs?: number): Promise<void>;
+    get<T extends {
+        id: string;
+    }>(object: string, ids: string[]): Promise<T[]>;
+    getSingleton<T>(object: string): Promise<T>;
+    /** Every object of a type. Filters are matched client-side by the caller. */
+    list<T extends {
+        id: string;
+    }>(object: string): Promise<T[]>;
+    create(object: string, value: Record<string, unknown>): Promise<string>;
+    update(object: string, id: string, patch: Record<string, unknown>): Promise<void>;
+    /**
+     * Mint an API key for the authenticated account through the self-service
+     * API, and return its secret, which is in the response and nowhere else.
+     *
+     * **`Inherit`, not a narrower set, and that is a finding rather than a
+     * shortcut.** `permissions` does take a `{'@type':'Replace', permissions:
+     * {…}}` form, and an empty one really does restrict — such a key is
+     * `forbidden` on every management method. But of some sixty candidate
+     * permission names tried against 0.16.20 on 2026-09-07, only
+     * `authenticate` and `impersonate` were accepted, and a key holding both
+     * is still `forbidden` on `x:Account/query`, `x:Domain/query`,
+     * `x:SystemSettings/get` and `x:ApiKey/query`. There is no name in this
+     * API's vocabulary that grants management access, so a scoped key cannot
+     * manage principals at all. `Inherit` is the only value that works.
+     *
+     * The key is therefore as powerful as the account it belongs to — the same
+     * power as its app password — and what it buys is not least privilege but
+     * two other things: it is typed `ApiKey`, which the `/email` section's revoke
+     * refuses to touch, and it goes as Bearer, so it carries no account name
+     * and cannot be used to sign in to mail as a person.
+     */
+    createApiKey(description: string): Promise<string>;
+    /**
+     * Mint an app password for the authenticated account through the
+     * self-service API. The secret is in the response and nowhere else. An app
+     * password is verified locally whatever directory the domain uses, which
+     * is what keeps the bootstrap signed in after the domain moves to OIDC
+     * (docs/plans/email/phase-4.md).
+     */
+    createAppPassword(description: string): Promise<string>;
+    /**
+     * Find-or-create by a caller-supplied match, then bring the found object
+     * to the wanted value. Returns the id either way, which is how later
+     * objects reference earlier ones.
+     */
+    upsert<T extends {
+        id: string;
+    }>(object: string, matches: (existing: T) => boolean, value: Record<string, unknown>, 
+    /**
+     * What to send when the object exists. Defaults to `value`; callers pass a
+     * subset when some of `value` is immutable once created (an `MtaRoute`'s
+     * `name`, which the server refuses to see again even unchanged).
+     */
+    patch?: Record<string, unknown>): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+}
+/**
+ * One entry of an Account's `credentials` list as `x:Account/get` returns
+ * it: every secret masked as `****`, the id the server assigned. A `List<T>`
+ * is a map keyed by index (see the header).
+ */
+export interface Credential {
+    '@type': 'Password' | 'AppPassword' | 'ApiKey';
+    credentialId?: string;
+    secret?: string;
+    [property: string]: unknown;
+}

package/dist/client.js

@@ -0,0 +1,235 @@
+/**
+ * Minimal client for Stalwart's management API, which is JMAP: every
+ * configuration object (Domain, AcmeProvider, MtaRoute, SystemSettings, …) is
+ * read and written with `x:<Object>/get|query|set` under the
+ * `urn:stalwart:jmap` capability. There is no REST surface for these in 0.16;
+ * the web admin and `stalwart-cli` speak exactly this.
+ *
+ * Shapes that differ from the docs and were confirmed on 0.16.20 (see
+ * docs/plans/email/phase-1-runbook.md, "What happened"):
+ *   - a `List<T>` field is a map keyed by index: `{"0": …}`, never an array;
+ *   - a `Map<T>` / `Set<T>` field is `{"value": true}`;
+ *   - a `SecretKey` from the environment is
+ *     `{"@type":"EnvironmentVariable","variableName":"…"}`;
+ *   - singletons are addressed with the id `singleton`.
+ *
+ * Authentication is Basic for a password or an app password, and **Bearer
+ * for an API key** — confirmed on 0.16.20, 2026-09-07: an `ApiKey` secret
+ * presented as Basic is refused with 401 whatever username accompanies it,
+ * and the same secret as `Authorization: Bearer` is accepted. That is why
+ * `StalwartAuth` is a union rather than a pair of strings. Until
+ * `Bootstrap/set` has run, the only account is the recovery admin from
+ * `STALWART_RECOVERY_ADMIN`; after it, the administrator it generated.
+ */
+const USING = ['urn:ietf:params:jmap:core', 'urn:stalwart:jmap'];
+/** API-key secrets are `API_`-prefixed on 0.16, which is how a caller can tell one from an app password. */
+export const API_KEY_PREFIX = 'API_';
+/** Which scheme a secret wants, from its own shape, for a caller holding one opaque string. */
+export function authFor(secret, user) {
+    if (secret.startsWith(API_KEY_PREFIX))
+        return { apiKey: secret };
+    if (!user) {
+        throw new Error('this secret is not an API key, so it is an account credential and needs the account it belongs to');
+    }
+    return { user, password: secret };
+}
+export class StalwartError extends Error {
+    method;
+    type;
+    constructor(method, type, description) {
+        super(`stalwart ${method} → ${type}${description ? `: ${description}` : ''}`);
+        this.method = method;
+        this.type = type;
+    }
+}
+export class StalwartClient {
+    base;
+    /**
+     * The finished `Authorization` header, computed once. A `#private` field,
+     * not a TypeScript `private` one: `private` is erased at compile time, so
+     * an instance holding the credential as an ordinary property serialises it
+     * — `JSON.stringify(client)` would put the secret in whatever logged it.
+     * A `#` field is genuinely inaccessible from outside and is skipped by
+     * `JSON.stringify`, so the only way to the credential is to send a request
+     * with it. The plaintext password is never stored.
+     */
+    #authorization;
+    /** @param baseUrl e.g. `https://email.example.com`, no trailing slash needed. */
+    constructor(baseUrl, auth) {
+        this.base = baseUrl.replace(/\/+$/, '');
+        if ('apiKey' in auth) {
+            this.#authorization = `Bearer ${auth.apiKey}`;
+        }
+        else {
+            const basic = Buffer.from(`${auth.user}:${auth.password}`, 'utf8').toString('base64');
+            this.#authorization = `Basic ${basic}`;
+        }
+    }
+    headers() {
+        return {
+            Authorization: this.#authorization,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+    }
+    /** One method call; throws `StalwartError` on a JMAP-level error. */
+    async call(method, args) {
+        const r = await fetch(`${this.base}/jmap`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ using: USING, methodCalls: [[method, args, 'c1']] }),
+        });
+        if (r.status === 401)
+            throw new StalwartError(method, 'unauthorized', 'wrong user or password');
+        if (!r.ok)
+            throw new StalwartError(method, `http ${r.status}`, (await r.text()).slice(0, 300));
+        const json = (await r.json());
+        const [name, payload] = json.methodResponses[0] ?? [];
+        if (name === 'error') {
+            throw new StalwartError(method, String(payload?.type ?? 'unknown'), payload?.description);
+        }
+        return payload;
+    }
+    /**
+     * Whether the server answers at all, and whether it is still in bootstrap
+     * mode. In bootstrap mode JMAP accepts only the `Bootstrap` object, so a
+     * `SystemSettings/get` is refused; that refusal is the signal.
+     */
+    async probe() {
+        let r;
+        try {
+            r = await fetch(`${this.base}/`, { redirect: 'manual' });
+        }
+        catch {
+            return 'down';
+        }
+        if (r.status >= 500)
+            return 'down';
+        try {
+            await this.call('x:SystemSettings/get', { ids: ['singleton'] });
+            return 'ready';
+        }
+        catch (e) {
+            if (e instanceof StalwartError && e.type === 'unauthorized')
+                throw e;
+            return 'bootstrap';
+        }
+    }
+    async waitFor(state, timeoutMs = 120_000) {
+        const started = Date.now();
+        while (Date.now() - started < timeoutMs) {
+            if ((await this.probe()) === state)
+                return;
+            await new Promise((res) => setTimeout(res, 5_000));
+        }
+        throw new Error(`stalwart at ${this.base} did not reach "${state}" within ${timeoutMs / 1000}s`);
+    }
+    async get(object, ids) {
+        const res = await this.call(`x:${object}/get`, { ids });
+        return res.list ?? [];
+    }
+    async getSingleton(object) {
+        const [one] = await this.get(object, ['singleton']);
+        if (!one)
+            throw new StalwartError(`x:${object}/get`, 'notFound', 'singleton');
+        return one;
+    }
+    /** Every object of a type. Filters are matched client-side by the caller. */
+    async list(object) {
+        const q = await this.call(`x:${object}/query`, {});
+        if (!q.ids?.length)
+            return [];
+        return this.get(object, q.ids);
+    }
+    async create(object, value) {
+        const res = await this.call(`x:${object}/set`, { create: { new: value } });
+        const failure = res.notCreated?.new;
+        if (failure) {
+            throw new StalwartError(`x:${object}/set`, failure.type, `${failure.description ?? ''}${failure.properties ? ` (${failure.properties.join(', ')})` : ''}`);
+        }
+        const id = res.created?.new?.id;
+        if (!id)
+            throw new StalwartError(`x:${object}/set`, 'noId', 'create returned no id');
+        return id;
+    }
+    async update(object, id, patch) {
+        const res = await this.call(`x:${object}/set`, { update: { [id]: patch } });
+        const failure = res.notUpdated?.[id];
+        if (failure) {
+            throw new StalwartError(`x:${object}/set`, failure.type, `${failure.description ?? ''}${failure.properties ? ` (${failure.properties.join(', ')})` : ''}`);
+        }
+    }
+    /**
+     * Mint an API key for the authenticated account through the self-service
+     * API, and return its secret, which is in the response and nowhere else.
+     *
+     * **`Inherit`, not a narrower set, and that is a finding rather than a
+     * shortcut.** `permissions` does take a `{'@type':'Replace', permissions:
+     * {…}}` form, and an empty one really does restrict — such a key is
+     * `forbidden` on every management method. But of some sixty candidate
+     * permission names tried against 0.16.20 on 2026-09-07, only
+     * `authenticate` and `impersonate` were accepted, and a key holding both
+     * is still `forbidden` on `x:Account/query`, `x:Domain/query`,
+     * `x:SystemSettings/get` and `x:ApiKey/query`. There is no name in this
+     * API's vocabulary that grants management access, so a scoped key cannot
+     * manage principals at all. `Inherit` is the only value that works.
+     *
+     * The key is therefore as powerful as the account it belongs to — the same
+     * power as its app password — and what it buys is not least privilege but
+     * two other things: it is typed `ApiKey`, which the `/email` section's revoke
+     * refuses to touch, and it goes as Bearer, so it carries no account name
+     * and cannot be used to sign in to mail as a person.
+     */
+    async createApiKey(description) {
+        const res = await this.call('x:ApiKey/set', {
+            create: { new: { description, permissions: { '@type': 'Inherit' } } },
+        });
+        const failure = res.notCreated?.new;
+        if (failure)
+            throw new StalwartError('x:ApiKey/set', failure.type, failure.description);
+        const secret = res.created?.new?.secret;
+        if (!secret)
+            throw new StalwartError('x:ApiKey/set', 'noSecret', 'create returned no secret');
+        return secret;
+    }
+    /**
+     * Mint an app password for the authenticated account through the
+     * self-service API. The secret is in the response and nowhere else. An app
+     * password is verified locally whatever directory the domain uses, which
+     * is what keeps the bootstrap signed in after the domain moves to OIDC
+     * (docs/plans/email/phase-4.md).
+     */
+    async createAppPassword(description) {
+        const res = await this.call('x:AppPassword/set', {
+            create: { new: { description, permissions: { '@type': 'Inherit' } } },
+        });
+        const failure = res.notCreated?.new;
+        if (failure) {
+            throw new StalwartError('x:AppPassword/set', failure.type, failure.description);
+        }
+        const secret = res.created?.new?.secret;
+        if (!secret)
+            throw new StalwartError('x:AppPassword/set', 'noSecret', 'create returned no secret');
+        return secret;
+    }
+    /**
+     * Find-or-create by a caller-supplied match, then bring the found object
+     * to the wanted value. Returns the id either way, which is how later
+     * objects reference earlier ones.
+     */
+    async upsert(object, matches, value, 
+    /**
+     * What to send when the object exists. Defaults to `value`; callers pass a
+     * subset when some of `value` is immutable once created (an `MtaRoute`'s
+     * `name`, which the server refuses to see again even unchanged).
+     */
+    patch = value) {
+        const found = (await this.list(object)).find(matches);
+        if (found) {
+            if (Object.keys(patch).length > 0)
+                await this.update(object, found.id, patch);
+            return { id: found.id, created: false };
+        }
+        return { id: await this.create(object, value), created: true };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Administer a Stalwart mail server over its JMAP management API: the
+ * domain, the mailboxes, their aliases, their app passwords and their
+ * quotas.
+ *
+ * **Not a JMAP mail client.** This speaks the `urn:stalwart:jmap` management
+ * extension — `x:Account`, `x:Domain`, `x:ApiKey` and their neighbours —
+ * which is a different surface from RFC 8620 and 8621. Reading and writing
+ * messages is `@wtfalch/mail`, and the two are kept apart on purpose: this
+ * one runs on a server holding a credential that, on 0.16, cannot be scoped
+ * and is as powerful as the account it belongs to, and that must never be
+ * one import away from something a browser bundles.
+ *
+ * The main entry is pure Node so a provisioning script can use it. The
+ * components live behind `@wtfalch/postmaster/react`.
+ */
+export { API_KEY_PREFIX, StalwartClient, StalwartError, authFor, type Credential, type StalwartAuth, } from './client.js';
+export { type Instance, openInstance } from './instance.js';
+export { loadOverview } from './load.js';
+export { applyObjects, mailObjects, ref, type MailObjectsInput, type PlannedObject, } from './objects.js';
+export { planMailboxes, withPassword } from './mailboxes.js';
+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';
+export { MailWriteRefused, newAccount, withAlias, withoutAlias, withoutAppPassword, } from './writes.js';
+export { addAlias, createMailbox, removeAlias, revokeAppPassword, type Applied, } from './apply.js';