@wtfalch/postmaster 0.1.0

package/dist/overview.js

@@ -0,0 +1,112 @@
+import { planMailboxes } from './mailboxes.js';
+function mode(m) {
+    if (!m)
+        return 'unknown';
+    return m['@type'] === 'Automatic' ? 'automatic' : m['@type'] === 'Manual' ? 'manual' : 'unknown';
+}
+const isNumber = (v) => typeof v === 'number' && Number.isFinite(v);
+/** The one number a `quotas` map is expected to carry, whatever key it turns out to use. */
+function quotaLimit(quotas) {
+    if (!quotas)
+        return null;
+    for (const key of ['storage', 'disk', 'diskQuota', 'quota']) {
+        if (isNumber(quotas[key]))
+            return quotas[key];
+    }
+    return null;
+}
+/** The instance's domain: the system default, else the one named, else the only one. */
+export function pickDomain(domains, settings, name) {
+    if (name)
+        return domains.find((d) => d.name === name) ?? null;
+    if (settings.defaultDomainId) {
+        const d = domains.find((d) => d.id === settings.defaultDomainId);
+        if (d)
+            return d;
+    }
+    return domains.length === 1 ? (domains[0] ?? null) : null;
+}
+export function overview(input, domainName) {
+    const domain = pickDomain(input.domains, input.settings, domainName);
+    if (!domain) {
+        const have = input.domains.map((d) => d.name).join(', ') || 'none';
+        throw new Error(domainName
+            ? `the instance has no domain ${domainName} (have: ${have})`
+            : `the instance has ${input.domains.length} domains and no default; set one in the web admin (have: ${have})`);
+    }
+    const apex = domain.name;
+    const mailHost = input.settings.defaultHostname ?? null;
+    const mx = input.mx
+        ? {
+            records: [...input.mx].map((r) => r.toLowerCase()).sort(),
+            pointsHere: mailHost !== null && input.mx.some((r) => r.toLowerCase() === mailHost.toLowerCase()),
+        }
+        : null;
+    const accounts = input.accounts
+        .filter((a) => a.domainId === domain.id)
+        .map((a) => ({
+        id: a.id,
+        local: a.name,
+        address: `${a.name}@${apex}`,
+        description: a.description ?? null,
+        role: a.roles?.['@type'] ?? 'unknown',
+        aliases: Object.values(a.aliases ?? {}).map((al) => ({
+            name: al.name,
+            enabled: al.enabled !== false,
+        })),
+        credentials: Object.values(a.credentials ?? {}).map((c) => ({
+            type: c['@type'],
+            description: typeof c.description === 'string' ? c.description : null,
+            credentialId: typeof c.credentialId === 'string' ? c.credentialId : null,
+        })),
+        quota: {
+            used: isNumber(a.usedDiskQuota) ? a.usedDiskQuota : null,
+            limit: quotaLimit(a.quotas),
+        },
+    }))
+        .sort((a, b) => a.local.localeCompare(b.local));
+    const people = peopleView(input.people, apex, accounts);
+    return {
+        domain: {
+            id: domain.id,
+            name: apex,
+            directory: domain.directoryId ? 'external' : 'internal',
+            certificate: mode(domain.certificateManagement),
+            dns: mode(domain.dnsManagement),
+            dkim: mode(domain.dkimManagement),
+            subAddressing: domain.subAddressing?.['@type'] === 'Enabled',
+            mailHost,
+            mx,
+        },
+        accounts,
+        people,
+    };
+}
+/** The part before the `@`. Typed as possibly absent by `noUncheckedIndexedAccess`; never absent in fact, since a string always splits into at least one piece. */
+function localPartOf(address) {
+    return (address.split('@')[0] ?? address).toLowerCase();
+}
+/**
+ * The people half, kept separate because it is the half with a refusal in
+ * it: an unreadable member list produces `known: false` and no claim about
+ * any mailbox.
+ */
+function peopleView(people, apex, accounts) {
+    if (people === null)
+        return { known: false };
+    // A person is matched to a mailbox by the local part of their address on
+    // this domain, the way `mail:sync` matches the issuer's user names. An
+    // address elsewhere says nothing about which mailbox is theirs.
+    const onDomain = people.filter((p) => p.email?.toLowerCase().endsWith(`@${apex.toLowerCase()}`));
+    const unmatched = people.filter((p) => !onDomain.includes(p));
+    const plan = planMailboxes(onDomain.map((p) => ({ userName: p.email })), accounts.map((a) => ({ name: a.local })));
+    const byLocal = new Map(onDomain.map((p) => [localPartOf(p.email), p]));
+    const pick = (locals) => locals.map((l) => byLocal.get(l)).filter((p) => !!p);
+    return {
+        known: true,
+        present: pick(plan.present),
+        missing: pick(plan.create),
+        orphaned: plan.orphaned,
+        unmatched,
+    };
+}

package/dist/react/controls.d.ts

@@ -0,0 +1,18 @@
+import type { WriteOutcome } from './types.js';
+/** One write, with its answer underneath and no way to press it twice. */
+export declare function WriteButton({ run, label, kind, confirm, }: {
+    run: () => Promise<WriteOutcome>;
+    label: string;
+    kind?: 'default' | 'primary' | 'ghost' | 'danger';
+    /** A sentence to agree to first. Present means the write is irreversible. */
+    confirm?: string;
+}): import("react").JSX.Element;
+/** A name and a button to add it: an alias, or a mailbox for someone. */
+export declare function AddByName({ run, label, placeholder, suffix, ariaLabel, }: {
+    run: (name: string) => Promise<WriteOutcome>;
+    label: string;
+    placeholder: string;
+    /** Shown after the field, so it is plain that the domain is not typed. */
+    suffix: string;
+    ariaLabel: string;
+}): import("react").JSX.Element;

package/dist/react/controls.js

@@ -0,0 +1,71 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, Callout, Input } from '@wtfalch/design';
+import { useState, useTransition } from 'react';
+/**
+ * The interactive leaves. Everything else this package draws is a server
+ * component; these are here because a control that must say "working" and
+ * then say what happened needs state, and only these do.
+ *
+ * The shape they share: the Server Action arrives as a prop, already bound to
+ * whatever it acts on, so this file names no action, holds no identifier and
+ * decides nothing. That is what lets the package hold them at all: the
+ * actions live in the consuming app, where the gate and the audit log are. It shows a result, keeps a control busy while a write is
+ * in flight, and asks twice before something irreversible.
+ *
+ * The result is deliberately a `Callout` and not a toast. A toast floats and
+ * expires, and the rule that comes with one is that anything disappearing on
+ * a timer must be safe to have missed. "That app password no longer works"
+ * is not, and neither is a refusal the person has to read to correct.
+ */
+function Result({ outcome }) {
+    if (!outcome)
+        return null;
+    return (_jsx(Callout, { tone: outcome.ok ? 'good' : 'bad', icon: true, children: outcome.message }));
+}
+/** One write, with its answer underneath and no way to press it twice. */
+export function WriteButton({ run, label, kind = 'default', confirm, }) {
+    const [pending, start] = useTransition();
+    const [outcome, setOutcome] = useState(null);
+    const [asking, setAsking] = useState(false);
+    const go = () => {
+        // Guarded like `AddByName` below. A second press during the round trip
+        // would start a second write from the same page state, and two different
+        // writes to one mailbox's list can lose one of them.
+        if (pending)
+            return;
+        setAsking(false);
+        start(async () => setOutcome(await run()));
+    };
+    // The confirmation is a question in the page rather than `window.confirm`:
+    // a browser dialog blocks the whole tab, cannot be styled or read out with
+    // the rest of the page, and gives no room to say what will actually happen.
+    if (asking) {
+        return (_jsxs("div", { className: "app-stack-tight", children: [_jsx(Callout, { tone: "warn", icon: true, children: confirm }), _jsxs("div", { className: "app-fields", children: [_jsx(Button, { kind: "danger", size: "sm", busy: pending, onPress: go, children: label }), _jsx(Button, { kind: "ghost", size: "sm", disabled: pending, onPress: () => setAsking(false), children: "Cancel" })] })] }));
+    }
+    return (_jsxs("div", { className: "app-stack-tight", children: [_jsx(Button, { kind: kind, size: "sm", busy: pending, onPress: () => (confirm ? setAsking(true) : go()), children: label }), _jsx(Result, { outcome: outcome })] }));
+}
+/** A name and a button to add it: an alias, or a mailbox for someone. */
+export function AddByName({ run, label, placeholder, suffix, ariaLabel, }) {
+    const [name, setName] = useState('');
+    const [pending, start] = useTransition();
+    const [outcome, setOutcome] = useState(null);
+    const go = () => {
+        const value = name.trim();
+        if (!value || pending)
+            return;
+        start(async () => {
+            const result = await run(value);
+            setOutcome(result);
+            // Cleared only on success. A refused name is the one the person has to
+            // see to correct, and blanking it makes them retype it to find out what
+            // was wrong.
+            if (result.ok)
+                setName('');
+        });
+    };
+    return (_jsxs("div", { className: "app-stack-tight", children: [_jsxs("div", { className: "app-fields", children: [_jsx(Input, { size: "sm", "aria-label": ariaLabel, value: name, placeholder: placeholder, disabled: pending, onChange: (e) => setName(e.target.value), onKeyDown: (e) => {
+                            if (e.key === 'Enter')
+                                go();
+                        } }), _jsx("span", { className: "app-quiet", children: suffix }), _jsx(Button, { kind: "default", size: "sm", busy: pending, disabled: !name.trim(), onPress: go, children: label })] }), _jsx(Result, { outcome: outcome })] }));
+}

package/dist/react/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The components that draw a mail instance's administration.
+ *
+ * Server components except `./controls`, which are the interactive leaves.
+ * Nothing here fetches, gates or decides: the consuming app reads the
+ * instance with the main entry, asks its own authorisation, binds its own
+ * Server Actions and passes the results in. `@wtfalch/design` is a peer
+ * dependency, and its stylesheet and the `app-*` layout classes are the
+ * consuming app's to load.
+ */
+export { DomainCard, Mailboxes, People, bytes, type MailActions } from './panel.js';
+export { AddByName, WriteButton } from './controls.js';
+export type { WriteOutcome } from './types.js';

package/dist/react/index.js

@@ -0,0 +1,12 @@
+/**
+ * The components that draw a mail instance's administration.
+ *
+ * Server components except `./controls`, which are the interactive leaves.
+ * Nothing here fetches, gates or decides: the consuming app reads the
+ * instance with the main entry, asks its own authorisation, binds its own
+ * Server Actions and passes the results in. `@wtfalch/design` is a peer
+ * dependency, and its stylesheet and the `app-*` layout classes are the
+ * consuming app's to load.
+ */
+export { DomainCard, Mailboxes, People, bytes } from './panel.js';
+export { AddByName, WriteButton } from './controls.js';

package/dist/react/panel.d.ts

@@ -0,0 +1,42 @@
+import type { AccountView, DomainView, PeopleView } from '../overview.js';
+import type { WriteOutcome } from './types.js';
+/**
+ * What a mail instance's administration looks like, as server components.
+ *
+ * Every one takes data and, where it can change something, an already-bound
+ * action. None of them fetches, gates or decides: the consuming app reads the
+ * instance, asks its own authorisation, binds its own Server Actions and
+ * hands the results here. That division is the same one `@wtfalch/threads`
+ * draws, and it is what keeps a package free of anybody's session.
+ */
+/**
+ * The writes a panel offers. Omit one and its control is not drawn.
+ *
+ * **These must be Server Actions, and they are bound rather than wrapped.**
+ * React refuses a function passed from a server component to a client one
+ * unless it is a Server Action — an inline `async () => act(id)` closure is
+ * not one, and the failure is at render rather than at build, which is the
+ * worst place to find it. `.bind(null, …)` on a Server Action produces
+ * another Server Action with the first arguments fixed, which is why every
+ * signature here takes its identifiers positionally and first.
+ */
+export interface MailActions {
+    readonly addAlias?: (accountId: string, name: string) => Promise<WriteOutcome>;
+    readonly removeAlias?: (accountId: string, name: string) => Promise<WriteOutcome>;
+    readonly revokeAppPassword?: (accountId: string, credentialId: string) => Promise<WriteOutcome>;
+    readonly createMailbox?: (local: string, description: string | null) => Promise<WriteOutcome>;
+}
+export declare function DomainCard({ domain }: {
+    domain: DomainView;
+}): import("react").JSX.Element;
+export declare function Mailboxes({ accounts, apex, actions, }: {
+    accounts: readonly AccountView[];
+    apex: string;
+    actions?: MailActions;
+}): import("react").JSX.Element;
+export declare function bytes(n: number): string;
+export declare function People({ people, apex, actions, }: {
+    people: PeopleView;
+    apex: string;
+    actions?: MailActions;
+}): import("react").JSX.Element;

package/dist/react/panel.js

@@ -0,0 +1,104 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { Callout, Card, Empty, Pill, Progress, Row, Rows } from '@wtfalch/design';
+import { AddByName, WriteButton } from './controls.js';
+export function DomainCard({ domain }) {
+    return (_jsx(Card, { icon: "cloud", title: domain.name, description: domain.mailHost
+            ? `Mail for this domain is delivered to ${domain.mailHost}.`
+            : 'The instance has no default hostname set.', children: _jsxs("div", { className: "app-stack-tight", children: [_jsxs("div", { className: "app-fields", children: [_jsxs(Pill, { tone: domain.dkim === 'automatic' ? 'good' : 'warn', children: ["DKIM ", domain.dkim === 'automatic' ? 'published automatically' : domain.dkim] }), _jsxs(Pill, { tone: domain.certificate === 'automatic' ? 'good' : 'warn', children: ["Certificate ", domain.certificate] }), _jsxs(Pill, { children: ["DNS ", domain.dns] }), _jsxs(Pill, { children: ["Passwords: ", domain.directory === 'external' ? 'the issuer’s' : 'the instance’s own'] }), domain.subAddressing ? _jsx(Pill, { children: "Sub-addressing on" }) : null] }), _jsx(MxLine, { domain: domain })] }) }));
+}
+/**
+ * What the world's resolver says, beside what the instance believes. The apex
+ * MX belongs to whoever provisioned the domain and not to the mail server, so
+ * a mismatch here is a real thing to see and not something this page can fix.
+ */
+function MxLine({ domain }) {
+    if (!domain.mx) {
+        return _jsx("p", { className: "app-quiet", children: "MX not checked: the resolver did not answer." });
+    }
+    if (domain.mx.records.length === 0) {
+        return (_jsxs(Callout, { tone: "bad", children: [domain.name, " publishes no MX record, so mail for it is not delivered anywhere."] }));
+    }
+    const list = domain.mx.records.join(', ');
+    return domain.mx.pointsHere ? (_jsxs("p", { className: "app-quiet", children: ["MX: ", list] })) : (_jsxs(Callout, { tone: "warn", children: ["MX for ", domain.name, " is ", list, ", which does not include ", domain.mailHost ?? 'this instance', ". Mail is delivered elsewhere."] }));
+}
+export function Mailboxes({ accounts, apex, actions = {}, }) {
+    return (_jsx(Card, { icon: "folder", title: "Mailboxes", description: `Every account on ${apex}, with its aliases, the credentials it signs in with, and what it is using.`, children: _jsx(Rows, { label: `Mailboxes on ${apex}`, empty: _jsxs(Empty, { icon: "folder", children: ["No mailboxes on ", apex, " yet."] }), children: accounts.map((account) => (_jsx(Row, { align: "start", name: account.address, pills: _jsx(AccountPills, { account: account }), hint: _jsx(AccountHint, { account: account }), trail: _jsx(Quota, { account: account }), below: _jsx(Manage, { account: account, apex: apex, actions: actions }) }, account.id))) }) }));
+}
+/**
+ * What can be changed about one mailbox. Nothing deletes a mailbox: that is
+ * somebody's mail, the instance is the system of record, and an irreversible
+ * thing that size belongs in the server's own admin.
+ */
+function Manage({ account, apex, actions, }) {
+    const appPasswords = account.credentials.filter((c) => c.type === 'AppPassword' && c.credentialId !== null);
+    const { addAlias, removeAlias, revokeAppPassword } = actions;
+    if (!addAlias && !removeAlias && !revokeAppPassword)
+        return null;
+    return (_jsxs("div", { className: "app-stack-tight", children: [addAlias ? (_jsx(AddByName, { ariaLabel: `New alias for ${account.address}`, label: "Add alias", placeholder: "sales", suffix: `@${apex}`, run: addAlias.bind(null, account.id) })) : null, removeAlias
+                ? account.aliases.map((alias) => (_jsx(WriteButton, { kind: "ghost", label: `Remove ${alias.name}@${apex}`, confirm: `Mail sent to ${alias.name}@${apex} will be rejected from then on. Anyone who has that address will need telling.`, run: removeAlias.bind(null, account.id, alias.name) }, alias.name)))
+                : null, revokeAppPassword
+                ? appPasswords.map((credential) => (_jsx(WriteButton, { kind: "ghost", label: `Revoke ${credential.description ?? 'an app password'}`, confirm: `Whatever is signed in with this app password stops receiving mail until somebody makes a new one on ${account.address}. There is no undo.`, run: revokeAppPassword.bind(null, account.id, credential.credentialId) }, credential.credentialId)))
+                : null] }));
+}
+function AccountPills({ account }) {
+    return (_jsxs(_Fragment, { children: [account.role !== 'User' ? _jsx(Pill, { inRow: true, children: account.role }) : null, account.aliases.map((alias) => (_jsxs(Pill, { inRow: true, tone: alias.enabled ? undefined : 'warn', children: [alias.name, alias.enabled ? '' : ' (off)'] }, alias.name)))] }));
+}
+/**
+ * The credentials, by type and count, and never a secret: the view they come
+ * from carries none. An account with no credential at all is the normal shape
+ * on a domain whose passwords an issuer holds, and is worth saying rather
+ * than leaving blank.
+ */
+function AccountHint({ account }) {
+    const counts = new Map();
+    for (const c of account.credentials)
+        counts.set(c.type, (counts.get(c.type) ?? 0) + 1);
+    const parts = [...counts].map(([type, n]) => (n === 1 ? type : `${type} ×${n}`));
+    return (_jsxs(_Fragment, { children: [account.description ? `${account.description} · ` : '', parts.length > 0 ? parts.join(', ') : 'no credentials of its own'] }));
+}
+/** Bytes as a human size. A null limit is the common case: no quota is set. */
+function Quota({ account }) {
+    const { used, limit } = account.quota;
+    if (used === null && limit === null)
+        return _jsx("span", { className: "app-quiet", children: "\u2014" });
+    if (limit === null || limit === 0) {
+        return _jsxs("span", { className: "app-quiet", children: [bytes(used ?? 0), " used"] });
+    }
+    return (_jsx(Progress, { value: used ?? 0, max: limit, label: `${account.address} storage`, detail: `${bytes(used ?? 0)} of ${bytes(limit)}` }));
+}
+export function bytes(n) {
+    const units = ['B', 'kB', 'MB', 'GB', 'TB'];
+    let value = n;
+    let unit = 0;
+    while (value >= 1000 && unit < units.length - 1) {
+        value /= 1000;
+        unit += 1;
+    }
+    return `${value >= 10 || unit === 0 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`;
+}
+export function People({ people, apex, actions = {}, }) {
+    if (!people.known) {
+        return (_jsx(Card, { icon: "chat", title: "People", description: `Who belongs to this organisation, and whether they have a mailbox on ${apex}.`, children: _jsx(Callout, { tone: "warn", icon: true, children: "Your role does not let you read this organisation's member list, so the mailboxes above cannot be matched to people. Nothing here says a mailbox is unused." }) }));
+    }
+    const rows = [
+        ...people.present.map((person) => ({ person, state: 'present' })),
+        ...people.missing.map((person) => ({ person, state: 'missing' })),
+        ...people.unmatched.map((person) => ({ person, state: 'unmatched' })),
+    ];
+    const { createMailbox } = actions;
+    return (_jsx(Card, { icon: "chat", title: "People", description: `Who belongs to this organisation, and whether they have a mailbox on ${apex}.`, children: _jsxs("div", { className: "app-stack-tight", children: [people.missing.length > 0 ? (_jsxs(Callout, { tone: "warn", children: [people.missing.length === 1
+                            ? 'One person has no mailbox yet.'
+                            : `${people.missing.length} people have no mailbox yet.`, ' ', "Mail to an unknown address is rejected, so the account has to exist before the first message arrives."] })) : null, _jsx(Rows, { label: "People in this organisation", empty: _jsx(Empty, { icon: "chat", children: "Nobody belongs to this organisation yet." }), children: rows.map(({ person, state }) => (_jsx(Row, { align: state === 'missing' ? 'start' : 'center', name: person.display, pills: _jsx(PersonPill, { state: state }), hint: person.email ?? 'no address at the issuer', actions: state === 'missing' && createMailbox ? (_jsx(WriteButton, { label: "Create mailbox", run: createMailbox.bind(null, localPart(person), person.email) })) : null }, person.id))) }), people.orphaned.length > 0 ? (_jsxs(Callout, { tone: "info", children: [people.orphaned.map((local) => `${local}@${apex}`).join(', '), ' ', people.orphaned.length === 1 ? 'has a mailbox but no' : 'have mailboxes but no', ' ', "matching person. A mailbox is somebody\u2019s data, so nothing here deletes one; do it in the server\u2019s own admin if that is right."] })) : null] }) }));
+}
+/** The local part of a person's own address, which is how a mailbox is matched to them. */
+function localPart(person) {
+    const address = person.email ?? '';
+    return address.split('@')[0] ?? address;
+}
+function PersonPill({ state }) {
+    if (state === 'present')
+        return (_jsx(Pill, { inRow: true, tone: "good", children: "Has a mailbox" }));
+    if (state === 'missing')
+        return (_jsx(Pill, { inRow: true, tone: "warn", children: "No mailbox" }));
+    return _jsx(Pill, { inRow: true, children: "Address elsewhere" });
+}

package/dist/react/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * What a write answers with. The consuming app's Server Actions return this
+ * shape and the controls render it; the package neither performs the write
+ * nor decides who may, because both of those belong where the session and
+ * the audit log are.
+ */
+export interface WriteOutcome {
+    readonly ok: boolean;
+    readonly message: string;
+}

package/dist/react/types.js

@@ -0,0 +1 @@
+export {};

package/dist/writes.d.ts

@@ -0,0 +1,62 @@
+import type { Credential } from './client.js';
+import type { WireAccount, WireAlias } from './overview.js';
+export declare class MailWriteRefused extends Error {
+}
+/**
+ * The `aliases` list to send so that `name` is also delivered to this
+ * account. Refuses a duplicate rather than sending one, because the server
+ * would accept two entries with the same name and the second would be
+ * unreachable noise.
+ *
+ * `name` is the local part only: an alias belongs to a domain, and the
+ * domain travels as `domainId`. A caller that passes `w@example.com` gets a
+ * refusal rather than an alias literally called `w@example.com`.
+ */
+export declare function withAlias(account: Pick<WireAccount, 'aliases'>, alias: {
+    name: string;
+    domainId: string;
+    description?: string | null;
+}): Record<string, WireAlias>;
+/**
+ * The `aliases` list to send so that `name` is no longer delivered here.
+ * Refuses when the alias is absent, so a stale page cannot send the whole
+ * list back unchanged and report that it removed something.
+ */
+export declare function withoutAlias(account: Pick<WireAccount, 'aliases'>, name: string): Record<string, WireAlias>;
+/**
+ * The `credentials` list to send so that one app password stops working and
+ * every other credential survives.
+ *
+ * Two refusals, both of which would otherwise be silent and severe. An entry
+ * whose type is not `AppPassword` is not this action's to touch: `Password`
+ * is the account's own password and removing it through a "revoke an app
+ * password" button would lock the person out of a domain that holds its own
+ * passwords; `ApiKey` is a machine's, including possibly this app's
+ * own credential (D3), so revoking it here could take the panel offline
+ * from inside the panel. And an id that matches nothing is refused rather
+ * than sending the list back unchanged and reporting success.
+ *
+ * Surviving entries keep their masked secrets, which the server reads as
+ * "leave this one alone" — the behaviour `withPassword` documents and
+ * relies on.
+ */
+export declare function withoutAppPassword(account: Pick<WireAccount, 'credentials'>, credentialId: string): Record<string, Credential>;
+/**
+ * The `Account` to create for a person, mirroring what
+ * `scripts/mail-sync.mts` sends, minus the password.
+ *
+ * **No credential, ever.** On a domain the issuer holds (`directoryId` set,
+ * which is every domain `mail-configure --mail-audience` has touched) the
+ * server refuses one anyway and the person signs in through
+ * auth.wtfalch.dev. On a domain with the instance's own directory a new
+ * account needs a first password, which `mail:sync` prints once to a
+ * terminal — a web page is the wrong place to show a secret and a worse
+ * place to store one, so this refuses that case and says which tool does it.
+ */
+export declare function newAccount(input: {
+    local: string;
+    domainId: string;
+    description?: string | null;
+    /** Whether the domain delegates passwords to an external directory. */
+    external: boolean;
+}): Record<string, unknown>;

package/dist/writes.js

@@ -0,0 +1,131 @@
+/**
+ * The payloads the write actions send, as pure functions over the wire
+ * shapes, so what gets sent to a real mail server is decided in a unit test
+ * rather than at the end of a Server Action.
+ *
+ * The same reasoning as `withPassword` in ./stalwart.ts, and the same rule
+ * that governs everything here: **a `List<T>` is a map keyed by index**
+ * (`{"0": …}`), never an array, and the server replaces the whole list when
+ * one is sent. So adding or removing one entry means sending every entry
+ * that survives, which is what makes these functions worth testing — a
+ * mistake does not fail, it silently deletes the entries left out.
+ *
+ * Indices are rebuilt contiguously from zero rather than preserved with a
+ * hole. A gap ("0" and "2", no "1") is not a shape the server has been seen
+ * to send, so it is not one to send back.
+ */
+/** A `List<T>` map, rebuilt contiguously from the entries that survive. */
+function indexed(values) {
+    return Object.fromEntries(values.map((v, i) => [String(i), v]));
+}
+/** The entries of a `List<T>`, in index order rather than object order. */
+function entriesOf(list) {
+    return Object.entries(list ?? {})
+        .sort(([a], [b]) => Number(a) - Number(b))
+        .map(([, v]) => v);
+}
+export class MailWriteRefused extends Error {
+}
+/**
+ * The `aliases` list to send so that `name` is also delivered to this
+ * account. Refuses a duplicate rather than sending one, because the server
+ * would accept two entries with the same name and the second would be
+ * unreachable noise.
+ *
+ * `name` is the local part only: an alias belongs to a domain, and the
+ * domain travels as `domainId`. A caller that passes `w@example.com` gets a
+ * refusal rather than an alias literally called `w@example.com`.
+ */
+export function withAlias(account, alias) {
+    const name = alias.name.trim().toLowerCase();
+    if (!name)
+        throw new MailWriteRefused('an alias needs a name');
+    if (name.includes('@')) {
+        throw new MailWriteRefused(`"${alias.name}" looks like a whole address; an alias is the local part only, and the domain is already known`);
+    }
+    const existing = entriesOf(account.aliases);
+    if (existing.some((a) => a.name.toLowerCase() === name)) {
+        throw new MailWriteRefused(`this mailbox already has the alias "${name}"`);
+    }
+    return indexed([
+        ...existing,
+        { enabled: true, name, domainId: alias.domainId, description: alias.description ?? null },
+    ]);
+}
+/**
+ * The `aliases` list to send so that `name` is no longer delivered here.
+ * Refuses when the alias is absent, so a stale page cannot send the whole
+ * list back unchanged and report that it removed something.
+ */
+export function withoutAlias(account, name) {
+    const wanted = name.trim().toLowerCase();
+    const existing = entriesOf(account.aliases);
+    const kept = existing.filter((a) => a.name.toLowerCase() !== wanted);
+    if (kept.length === existing.length) {
+        throw new MailWriteRefused(`this mailbox has no alias "${name}"`);
+    }
+    return indexed(kept);
+}
+/**
+ * The `credentials` list to send so that one app password stops working and
+ * every other credential survives.
+ *
+ * Two refusals, both of which would otherwise be silent and severe. An entry
+ * whose type is not `AppPassword` is not this action's to touch: `Password`
+ * is the account's own password and removing it through a "revoke an app
+ * password" button would lock the person out of a domain that holds its own
+ * passwords; `ApiKey` is a machine's, including possibly this app's
+ * own credential (D3), so revoking it here could take the panel offline
+ * from inside the panel. And an id that matches nothing is refused rather
+ * than sending the list back unchanged and reporting success.
+ *
+ * Surviving entries keep their masked secrets, which the server reads as
+ * "leave this one alone" — the behaviour `withPassword` documents and
+ * relies on.
+ */
+export function withoutAppPassword(account, credentialId) {
+    const existing = entriesOf(account.credentials);
+    const target = existing.find((c) => c.credentialId === credentialId);
+    if (!target) {
+        throw new MailWriteRefused('that credential is not on this mailbox any more');
+    }
+    if (target['@type'] !== 'AppPassword') {
+        throw new MailWriteRefused(`that credential is a ${target['@type']}, not an app password; only app passwords are revoked here`);
+    }
+    return indexed(existing.filter((c) => c !== target));
+}
+/**
+ * The `Account` to create for a person, mirroring what
+ * `scripts/mail-sync.mts` sends, minus the password.
+ *
+ * **No credential, ever.** On a domain the issuer holds (`directoryId` set,
+ * which is every domain `mail-configure --mail-audience` has touched) the
+ * server refuses one anyway and the person signs in through
+ * auth.wtfalch.dev. On a domain with the instance's own directory a new
+ * account needs a first password, which `mail:sync` prints once to a
+ * terminal — a web page is the wrong place to show a secret and a worse
+ * place to store one, so this refuses that case and says which tool does it.
+ */
+export function newAccount(input) {
+    const local = input.local.trim().toLowerCase();
+    if (!local)
+        throw new MailWriteRefused('a mailbox needs a name');
+    if (local.includes('@')) {
+        throw new MailWriteRefused(`"${input.local}" looks like a whole address; a mailbox is named by its local part`);
+    }
+    if (!input.external) {
+        throw new MailWriteRefused('this domain keeps its own passwords, so a new mailbox needs a first password shown once. Create it with `pnpm mail:sync --name <app> --apply`, which prints it to a terminal rather than a web page.');
+    }
+    return {
+        '@type': 'User',
+        name: local,
+        domainId: input.domainId,
+        description: input.description ?? null,
+        roles: { '@type': 'User' },
+        permissions: { '@type': 'Inherit' },
+        encryptionAtRest: { '@type': 'Disabled' },
+        quotas: {},
+        aliases: {},
+        memberGroupIds: {},
+    };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@wtfalch/postmaster",
+  "version": "0.1.0",
+  "description": "Administer a Stalwart mail server: its domain, mailboxes, aliases, app passwords and quotas, over the JMAP management API.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wtfalch/postmaster.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@wtfalch/design": ">=0.4.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@wtfalch/design": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "@types/react": "^19.0.8",
+    "@wtfalch/design": "^0.4.0",
+    "react": "^19.0.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}