@wtfalch/postmaster 0.1.0

package/dist/index.js

@@ -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, } from './client.js';
+export { openInstance } from './instance.js';
+export { loadOverview } from './load.js';
+export { applyObjects, mailObjects, ref, } from './objects.js';
+export { planMailboxes, withPassword } from './mailboxes.js';
+export { overview, pickDomain, } from './overview.js';
+export { MailWriteRefused, newAccount, withAlias, withoutAlias, withoutAppPassword, } from './writes.js';
+export { addAlias, createMailbox, removeAlias, revokeAppPassword, } from './apply.js';

package/dist/instance.d.ts

@@ -0,0 +1,36 @@
+import { StalwartClient } from './client.js';
+/**
+ * A mail instance and the credential this program acts on it with.
+ *
+ * Deliberately not built from environment variables here: what those are
+ * called is the consuming app's business, and a package that read
+ * `process.env` would decide it for every consumer. The app reads its own
+ * names and calls `openInstance`; `@wtfalch/postmaster` only insists that
+ * the URL is https, because a Basic credential over http is the credential
+ * in clear.
+ */
+export interface Instance {
+    readonly url: string;
+    /**
+     * The account this program acts as, or `null` when an API key acts for
+     * itself. An API key authenticates as Bearer and carries no account name;
+     * a password or app password is an account credential and has nobody to be
+     * without one. `revokeAppPassword` uses this to recognise the account the
+     * caller signs in as, so that a program cannot revoke its own credential.
+     */
+    readonly user: string | null;
+    readonly client: StalwartClient;
+}
+/**
+ * An instance from a URL and one opaque secret, with the scheme chosen from
+ * the secret's own shape by `authFor`. Confirmed against Stalwart 0.16.20:
+ * an API key presented as Basic is refused with 401 whatever username
+ * accompanies it, and an account credential has nothing to authenticate as
+ * without its account.
+ */
+export declare function openInstance(input: {
+    url: string;
+    secret: string;
+    /** Required unless the secret is an API key. */
+    user?: string;
+}): Instance;

package/dist/instance.js

@@ -0,0 +1,20 @@
+import { StalwartClient, authFor } from './client.js';
+/**
+ * An instance from a URL and one opaque secret, with the scheme chosen from
+ * the secret's own shape by `authFor`. Confirmed against Stalwart 0.16.20:
+ * an API key presented as Basic is refused with 401 whatever username
+ * accompanies it, and an account credential has nothing to authenticate as
+ * without its account.
+ */
+export function openInstance(input) {
+    const url = input.url.trim().replace(/\/+$/, '');
+    if (!/^https:\/\//.test(url)) {
+        throw new Error(`a mail instance URL must be https, got "${input.url}"`);
+    }
+    const auth = authFor(input.secret, input.user);
+    return {
+        url,
+        user: 'apiKey' in auth ? null : auth.user,
+        client: new StalwartClient(url, auth),
+    };
+}

package/dist/load.d.ts

@@ -0,0 +1,11 @@
+import type { Instance } from './instance.js';
+import { type Overview, type Person } from './overview.js';
+/**
+ * Fetches what `overview()` reads: every domain and account on the instance,
+ * the system settings that say which domain is the instance's own, and the
+ * apex's MX records from the resolver this server uses. The MX lookup is
+ * the one fact here that does not come from the instance: what the world
+ * sees, beside what the instance believes. A resolver failure is not the
+ * page's failure; it renders as "not checked".
+ */
+export declare function loadOverview(instance: Instance, people: readonly Person[] | null, domainName?: string): Promise<Overview>;

package/dist/load.js

@@ -0,0 +1,33 @@
+import { resolveMx } from 'node:dns/promises';
+import { overview, } from './overview.js';
+/**
+ * Fetches what `overview()` reads: every domain and account on the instance,
+ * the system settings that say which domain is the instance's own, and the
+ * apex's MX records from the resolver this server uses. The MX lookup is
+ * the one fact here that does not come from the instance: what the world
+ * sees, beside what the instance believes. A resolver failure is not the
+ * page's failure; it renders as "not checked".
+ */
+export async function loadOverview(instance, people, domainName) {
+    const { client } = instance;
+    const [domains, accounts, settings] = await Promise.all([
+        client.list('Domain'),
+        client.list('Account'),
+        client.getSingleton('SystemSettings'),
+    ]);
+    const first = overview({ domains, accounts, settings, people, mx: null }, domainName);
+    const mx = await lookupMx(first.domain.name);
+    return mx ? overview({ domains, accounts, settings, people, mx }, domainName) : first;
+}
+async function lookupMx(apex) {
+    try {
+        const records = await Promise.race([
+            resolveMx(apex),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 3_000)),
+        ]);
+        return records.sort((a, b) => a.priority - b.priority).map((r) => r.exchange);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/mailboxes.d.ts

@@ -0,0 +1,23 @@
+import type { Credential } from './client.js';
+/** Pure: who should have a mailbox, and who has one that no longer matches a human. */
+export declare function planMailboxes(humans: Array<{
+    userName: string;
+    email?: string;
+}>, accounts: Array<{
+    name: string;
+    description?: string | null;
+}>): {
+    create: string[];
+    present: string[];
+    orphaned: string[];
+};
+/**
+ * Pure: the `credentials` list to send so that `secret` becomes the
+ * account's password and every other credential (app passwords, API keys)
+ * survives. Confirmed against the server's principal mapping on 0.16: an
+ * entry sent back with a masked secret keeps the stored one; a Password
+ * entry with its `credentialId` and a plain secret is re-hashed; a Password
+ * entry without an id is appended, and only one may exist, so an existing
+ * one is replaced rather than added to.
+ */
+export declare function withPassword(credentials: Record<string, Credential> | undefined, secret: string): Record<string, Credential>;

package/dist/mailboxes.js

@@ -0,0 +1,35 @@
+// ── mailboxes for people ────────────────────────────────────────────────
+/** Pure: who should have a mailbox, and who has one that no longer matches a human. */
+export function planMailboxes(humans, accounts) {
+    const wanted = new Set(humans.map((h) => (h.userName.split('@')[0] ?? h.userName).toLowerCase()));
+    const have = new Set(accounts.map((a) => a.name.toLowerCase()));
+    return {
+        create: [...wanted].filter((n) => !have.has(n)).sort(),
+        present: [...wanted].filter((n) => have.has(n)).sort(),
+        orphaned: [...have].filter((n) => !wanted.has(n)).sort(),
+    };
+}
+/**
+ * Pure: the `credentials` list to send so that `secret` becomes the
+ * account's password and every other credential (app passwords, API keys)
+ * survives. Confirmed against the server's principal mapping on 0.16: an
+ * entry sent back with a masked secret keeps the stored one; a Password
+ * entry with its `credentialId` and a plain secret is re-hashed; a Password
+ * entry without an id is appended, and only one may exist, so an existing
+ * one is replaced rather than added to.
+ */
+export function withPassword(credentials, secret) {
+    const out = { ...(credentials ?? {}) };
+    // Found by entry rather than by key, so the existing credential is in hand
+    // and the spread below cannot be over a `possibly undefined` lookup. The
+    // index signature says every read might miss; here it provably does not.
+    const existing = Object.entries(out).find(([, c]) => c['@type'] === 'Password');
+    if (existing) {
+        const [key, credential] = existing;
+        out[key] = { ...credential, secret };
+        return out;
+    }
+    const next = Object.keys(out).reduce((n, k) => Math.max(n, Number(k) + 1), 0);
+    out[String(next)] = { '@type': 'Password', secret };
+    return out;
+}

package/dist/objects.d.ts

@@ -0,0 +1,47 @@
+import type { StalwartClient } from './client.js';
+export interface MailObjectsInput {
+    /** The email domain, e.g. `example.com`. */
+    apex: string;
+    /** The MX target and TLS name, e.g. `mx.example.com`. */
+    mailHost: string;
+    /** ACME account contact. */
+    contact: string;
+    /** Container env variable holding the zone-scoped Cloudflare DNS token. */
+    dnsTokenVar: string;
+    /** Container env variable holding the Resend API key used as SMTP password. */
+    resendTokenVar: string;
+    /**
+     * The project's identity provider, once the mail applications are
+     * registered there (docs/plans/email.md E3, phase-4.md slice 1): tokens
+     * from `issuerUrl` for `audience` (the ZITADEL project id) sign people in,
+     * on the domain and as the server's default. Absent, the domain keeps the
+     * internal directory and people have passwords.
+     */
+    oidc?: {
+        issuerUrl: string;
+        audience: string;
+    };
+}
+/** A value that names an object created earlier in the same plan. */
+export declare const ref: (key: string) => {
+    $ref: string;
+};
+export interface PlannedObject {
+    key: string;
+    object: string;
+    /** Property values that identify an existing object of this type. */
+    match: Record<string, unknown>;
+    value: Record<string, unknown>;
+}
+/**
+ * The full configuration of an instance as data, in dependency order. Pure,
+ * so it is unit-tested; `applyObjects` resolves the `$ref`s against the
+ * server. What each object is for is in docs/plans/email.md (E3 to E5).
+ */
+export declare function mailObjects(i: MailObjectsInput): PlannedObject[];
+/**
+ * Apply a plan: singletons are updated, `Action`s are created (they are
+ * fire-and-forget), everything else is upserted by its `match` properties.
+ * Returns the id of every object, keyed by plan key.
+ */
+export declare function applyObjects(client: StalwartClient, plan: PlannedObject[], log: (line: string) => void): Promise<Record<string, string>>;

package/dist/objects.js

@@ -0,0 +1,167 @@
+/** A value that names an object created earlier in the same plan. */
+export const ref = (key) => ({ $ref: key });
+const env = (variableName) => ({ '@type': 'EnvironmentVariable', variableName });
+/**
+ * The full configuration of an instance as data, in dependency order. Pure,
+ * so it is unit-tested; `applyObjects` resolves the `$ref`s against the
+ * server. What each object is for is in docs/plans/email.md (E3 to E5).
+ */
+export function mailObjects(i) {
+    const oidcDescription = i.oidc ? `${i.oidc.issuerUrl} (${i.apex})` : undefined;
+    const directory = i.oidc
+        ? [
+            {
+                key: 'oidc',
+                object: 'Directory',
+                match: { description: oidcDescription },
+                value: {
+                    '@type': 'Oidc',
+                    description: oidcDescription,
+                    issuerUrl: i.oidc.issuerUrl,
+                    requireAudience: i.oidc.audience,
+                    requireScopes: { openid: true, email: true },
+                    claimUsername: 'preferred_username',
+                    usernameDomain: i.apex,
+                    claimName: 'name',
+                },
+            },
+        ]
+        : [];
+    return [
+        {
+            key: 'acme',
+            object: 'AcmeProvider',
+            match: { challengeType: 'Dns01' },
+            value: {
+                contact: { [i.contact]: true },
+                challengeType: 'Dns01',
+                renewBefore: 'R23',
+                maxRetries: 10,
+            },
+        },
+        {
+            key: 'dns',
+            object: 'DnsServer',
+            match: { description: `Cloudflare ${i.apex}` },
+            value: {
+                '@type': 'Cloudflare',
+                description: `Cloudflare ${i.apex}`,
+                secret: env(i.dnsTokenVar),
+            },
+        },
+        ...directory,
+        {
+            key: 'domain',
+            object: 'Domain',
+            match: { name: i.apex },
+            // publishRecords is DKIM only, deliberately: the default list rewrites
+            // the apex SPF, DMARC and MX and adds zone-wide CAA records (phase 1,
+            // 2026-09-06). Those records are the bootstrap's to write.
+            value: {
+                name: i.apex,
+                certificateManagement: { '@type': 'Automatic', acmeProviderId: ref('acme') },
+                dnsManagement: {
+                    '@type': 'Automatic',
+                    dnsServerId: ref('dns'),
+                    origin: i.apex,
+                    publishRecords: { dkim: true },
+                },
+                dkimManagement: { '@type': 'Automatic' },
+                subAddressing: { '@type': 'Enabled' },
+                // Once set, a re-run without `oidc` leaves it: removing a directory
+                // is the operator's decision, not a missing flag's.
+                ...(i.oidc ? { directoryId: ref('oidc') } : {}),
+            },
+        },
+        {
+            key: 'relay',
+            object: 'MtaRoute',
+            match: { name: 'resend' },
+            value: {
+                '@type': 'Relay',
+                name: 'resend',
+                description: 'Every outbound message relays through Resend (docs/plans/email.md, E4)',
+                address: 'smtp.resend.com',
+                port: 465,
+                protocol: 'smtp',
+                implicitTls: true,
+                authUsername: 'resend',
+                authSecret: env(i.resendTokenVar),
+            },
+        },
+        {
+            key: 'outbound',
+            object: 'MtaOutboundStrategy',
+            match: { id: 'singleton' },
+            value: { route: { else: "'resend'" } },
+        },
+        {
+            key: 'system',
+            object: 'SystemSettings',
+            match: { id: 'singleton' },
+            value: { defaultHostname: i.mailHost, defaultDomainId: ref('domain') },
+        },
+        ...(i.oidc
+            ? [
+                {
+                    key: 'auth',
+                    object: 'Authentication',
+                    match: { id: 'singleton' },
+                    value: { directoryId: ref('oidc') },
+                },
+            ]
+            : []),
+        {
+            key: 'reload',
+            object: 'Action',
+            match: {},
+            value: { '@type': 'ReloadSettings' },
+        },
+    ];
+}
+function resolve(value, ids) {
+    if (Array.isArray(value))
+        return value.map((v) => resolve(v, ids));
+    if (value && typeof value === 'object') {
+        const o = value;
+        if (typeof o.$ref === 'string') {
+            const id = ids[o.$ref];
+            if (!id)
+                throw new Error(`unresolved reference "${o.$ref}"`);
+            return id;
+        }
+        return Object.fromEntries(Object.entries(o).map(([k, v]) => [k, resolve(v, ids)]));
+    }
+    return value;
+}
+/**
+ * Apply a plan: singletons are updated, `Action`s are created (they are
+ * fire-and-forget), everything else is upserted by its `match` properties.
+ * Returns the id of every object, keyed by plan key.
+ */
+export async function applyObjects(client, plan, log) {
+    const ids = {};
+    for (const p of plan) {
+        const value = resolve(p.value, ids);
+        if (p.match.id === 'singleton') {
+            await client.update(p.object, 'singleton', value);
+            ids[p.key] = 'singleton';
+            log(`${p.object}: updated`);
+            continue;
+        }
+        if (p.object === 'Action') {
+            await client.create(p.object, value);
+            log(`${p.object}: ${String(value['@type'])}`);
+            continue;
+        }
+        const entries = Object.entries(p.match);
+        // The match properties identified the object, so they are equal already;
+        // they are also where immutable properties live (`name`), and the server
+        // refuses an update that mentions one. They stay out of the patch.
+        const patch = Object.fromEntries(Object.entries(value).filter(([k]) => !(k in p.match)));
+        const { id, created } = await client.upsert(p.object, (existing) => entries.every(([k, v]) => existing[k] === v), value, patch);
+        ids[p.key] = id;
+        log(`${p.object}: ${created ? 'created' : 'updated'} (${id})`);
+    }
+    return ids;
+}

package/dist/overview.d.ts

@@ -0,0 +1,177 @@
+import type { Credential } from './client.js';
+/**
+ * The read-only view of one mail instance: the domain, its mailboxes and the
+ * organisation's people beside them. `overview()` is pure over the wire
+ * shapes the management API returns and the people the app knows, so it is
+ * unit-tested; `loadOverview` in ./load.ts fetches and calls it.
+ *
+ * Wire shapes are as `x:<Object>/get` returns them on 0.16 (the header of
+ * ./stalwart.ts, docs/plans/email/phase-1-runbook.md): a `List<T>` is a map
+ * keyed by index, never an array. Only the properties the view reads are
+ * typed, and **nothing is passed through**: every field of the view is named
+ * and rebuilt here, so a wire property nobody listed cannot reach the page.
+ * That is what keeps a credential's secret out of the view whatever shape a
+ * future server version gives it, and it is why there is no spread anywhere
+ * below — do not add one.
+ */
+/**
+ * The server sends a good deal more than any of these interfaces declare —
+ * a `Domain` carries a multi-kilobyte `dnsZoneFile`, an `Account` carries
+ * `emailAddress`, `locale`, `timeZone`, `externalId` and more (confirmed on
+ * 0.16.20, 2026-09-07). The index signature admits all of it *and* is the
+ * point: the extra fields exist, are typed as `unknown`, and can therefore
+ * only reach the view if someone names them explicitly. There is no spread
+ * below, so none of them does.
+ */
+export interface WireDomain {
+    [property: string]: unknown;
+    id: string;
+    name: string;
+    directoryId?: string | null;
+    certificateManagement?: Managed | null;
+    dnsManagement?: (Managed & {
+        publishRecords?: Record<string, boolean>;
+    }) | null;
+    dkimManagement?: Managed | null;
+    subAddressing?: Managed | null;
+}
+/**
+ * One of the server's `@type`-tagged management blocks. Each carries its own
+ * settings beside the tag — an ACME provider id, the DKIM algorithms and
+ * selector template, the DNS server id — and the view reads only the tag.
+ */
+export interface Managed {
+    [property: string]: unknown;
+    '@type': string;
+}
+export interface WireAlias {
+    [property: string]: unknown;
+    enabled?: boolean;
+    name: string;
+    domainId?: string;
+    description?: string | null;
+}
+export interface WireAccount {
+    [property: string]: unknown;
+    id: string;
+    name: string;
+    domainId: string;
+    description?: string | null;
+    /** `{'@type': 'Admin'}` for the instance's administrator, `'User'` for a person. */
+    roles?: {
+        '@type': string;
+    } | null;
+    credentials?: Record<string, Credential>;
+    aliases?: Record<string, WireAlias>;
+    /**
+     * Present and an object, but every account seen so far has it empty, so
+     * the key a *set* quota uses is still unknown — hence `quotaLimit`'s list
+     * of candidates and its `null` when none matches. Never guess a number.
+     */
+    quotas?: Record<string, unknown> | null;
+    /** Bytes. Confirmed real on 0.16.20 (a live account reported 12362). */
+    usedDiskQuota?: number | null;
+}
+export interface WireSystemSettings {
+    [property: string]: unknown;
+    defaultHostname?: string | null;
+    defaultDomainId?: string | null;
+}
+/** A person the app knows, from the operator tenant's memberships. */
+export interface Person {
+    readonly id: string;
+    readonly display: string;
+    readonly email: string | null;
+}
+export interface OverviewInput {
+    readonly domains: readonly WireDomain[];
+    readonly accounts: readonly WireAccount[];
+    readonly settings: WireSystemSettings;
+    /**
+     * The organisation's people, or `null` when the caller could not read them
+     * — which is not the same as an organisation with nobody in it, and must
+     * not be flattened into one. See `PeopleView`.
+     */
+    readonly people: readonly Person[] | null;
+    /** MX records the resolver returned for the apex, or null when the lookup was not done. */
+    readonly mx?: readonly string[] | null;
+}
+export type Mode = 'automatic' | 'manual' | 'unknown';
+export interface DomainView {
+    /** The server's id for the domain, which every write names as `domainId`. */
+    readonly id: string;
+    readonly name: string;
+    /** Where passwords live: the issuer's directory, or the instance's own. */
+    readonly directory: 'external' | 'internal';
+    readonly certificate: Mode;
+    readonly dns: Mode;
+    readonly dkim: Mode;
+    readonly subAddressing: boolean;
+    /** The instance's own hostname, the MX target and TLS name. */
+    readonly mailHost: string | null;
+    /** The apex's MX records as resolved, and whether the instance is among them. */
+    readonly mx: {
+        readonly records: readonly string[];
+        readonly pointsHere: boolean;
+    } | null;
+}
+export interface CredentialSummary {
+    readonly type: 'Password' | 'AppPassword' | 'ApiKey' | string;
+    readonly description: string | null;
+    /**
+     * The server's opaque id for this credential, which a revoke names. Not a
+     * secret — the secret is masked to `****` on the wire and never leaves
+     * `overview()` at all — but the only handle a caller has on one entry of
+     * a list whose entries are otherwise told apart by position.
+     */
+    readonly credentialId: string | null;
+}
+export interface AccountView {
+    readonly id: string;
+    readonly local: string;
+    readonly address: string;
+    readonly description: string | null;
+    readonly role: string;
+    readonly aliases: readonly {
+        name: string;
+        enabled: boolean;
+    }[];
+    /** Secrets never reach this: only the type and the description of each credential. */
+    readonly credentials: readonly CredentialSummary[];
+    readonly quota: {
+        readonly used: number | null;
+        readonly limit: number | null;
+    };
+}
+/**
+ * Who belongs, set against who has a mailbox — or `known: false`, meaning
+ * the caller could not read the member list.
+ *
+ * The distinction is load-bearing rather than tidy. Every field below is
+ * computed by subtracting one set from the other, so an unknown people list
+ * silently read as an empty one would put *every* mailbox in `orphaned` and
+ * the page would tell someone to go and delete live mail. There is no
+ * `orphaned` to report when the people are unknown, so the type does not
+ * offer one.
+ */
+export type PeopleView = {
+    readonly known: false;
+} | {
+    readonly known: true;
+    /** People with a mailbox. */
+    readonly present: readonly Person[];
+    /** People with an address on the domain and no mailbox yet (slice 2 creates these). */
+    readonly missing: readonly Person[];
+    /** Mailboxes no person matches, by local part. */
+    readonly orphaned: readonly string[];
+    /** People whose address is not on this domain, so no local part can be matched. */
+    readonly unmatched: readonly Person[];
+};
+export interface Overview {
+    readonly domain: DomainView;
+    readonly accounts: readonly AccountView[];
+    readonly people: PeopleView;
+}
+/** The instance's domain: the system default, else the one named, else the only one. */
+export declare function pickDomain(domains: readonly WireDomain[], settings: WireSystemSettings, name?: string): WireDomain | null;
+export declare function overview(input: OverviewInput, domainName?: string): Overview;