@rapidmx/web-client 0.37.1 → 0.39.0

package/dist/lib/admin/domainsApi.d.ts

@@ -24,6 +24,23 @@ export interface Domain {
     /** When set, this domain is a pure alias of the domain named here - it has no mailboxes of its own; mail
      * addressed to it is delivered to the matching mailbox on the domain it aliases instead. */
     aliasOf?: string;
+    /** Where the domain came from: `"seed"` for one the server added at start-up from the installation's own list, `"console"` for one added through
+     * the API. Unset on a domain from before this was recorded, which counts as added through the console. Server-managed. */
+    origin?: "seed" | "console" | null;
+    /** The DNS provider config (`system/dns-providers`) that publishes this domain's records, `null` or unset for "manual": the administrator adds
+     * them by hand. Changes only through `assignDnsProvider()`. */
+    dnsProviderUid?: string | null;
+    /** Whether RapidMX owns the domain's root TXT records (to publish SPF there) and which other values it keeps in them. Unset means not managed;
+     * `keep` and `spf` stay after an opt-out. Changes only through `updateApexTxt()`. */
+    apexTxt?: ApexTxtSettings | null;
+    /** The DKIM key rotation in progress, if any (`getDkimRotation()` is the console's view of it). Server-managed: changes only through `rotateDkim()`,
+     * `cancelDkimRotation()` and `setDkimRotationPaused()`. */
+    dkimRotation?: DkimRotationState | null;
+}
+export interface ApexTxtSettings {
+    managed: boolean;
+    keep: string[];
+    spf?: string;
 }
 /** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
  * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
@@ -56,7 +73,22 @@ export declare function deleteDomain(uid: string, version: number, client?: ApiC
  * Idempotent on an already-verified domain; a still-unverified result is not an error (only
  * `lastCheckedAt` advances) — always returns the domain's current state either way. */
 export declare function verifyDomain(uid: string, client?: ApiClient): Promise<Domain>;
-export type DnsRecordType = "ownership" | "mx" | "spf" | "dkim" | "dmarc" | "openpgpkey_cname" | "autodiscover_cname" | "autodiscover_srv";
+export type DnsRecordType = "ownership" | "mx" | "spf" | "dkim" | "dkim_next" | "dkim_previous" | "dmarc" | "openpgpkey_cname" | "autodiscover_cname" | "autodiscover_srv";
+/** How a record is published: `published` (the DNS controller applied it and the live lookup sees it), `pending`, `conflict` (a record this deployment
+ * doesn't own is there) or `manual` (the administrator adds it, see `DnsManualReason`). */
+export type DnsPublicationState = "published" | "pending" | "conflict" | "manual";
+/** Why a published record is in conflict: a record of the same type is there that this deployment doesn't own (`not_owned`, which a takeover can
+ * overwrite), or records of another type that can't stand next to it (`type_mismatch`: a CNAME wanted where other records are, or other records wanted
+ * where a CNAME is), which RapidMX never deletes or takes over and the administrator deletes at their DNS host. */
+export type DnsConflictReason = "not_owned" | "type_mismatch";
+/** A live record in the way of a published one (`type_mismatch`): its type and its value as text. */
+export interface DnsExistingRecord {
+    type: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "SRV";
+    value: string;
+}
+/** Why a record is `manual`: no provider is assigned, the provider can't hold the record's kind, the name lies outside the provider's zones, or the
+ * record belongs to the root TXT set, which RapidMX manages only on the administrator's opt-in. */
+export type DnsManualReason = "no_provider" | "kind_unsupported" | "outside_zones" | "apex_txt_unmanaged";
 /** One mail-related DNS record this server recommends for a domain, live-checked against real DNS —
  * purely diagnostic, never mutates anything (unlike `verifyDomain`). The two `autodiscover_*` types are only
  * ever present while `@rapidmx/autodiscover-plugin` is active for this deployment. */
@@ -71,5 +103,88 @@ export interface DnsRecordCheck {
     found: boolean;
     matches: boolean;
     actualValue?: string;
+    /** Whether, and how, the DNS controller publishes this record. Present only on a server that publishes, and only for a configured record. */
+    publication?: DnsPublicationState;
+    manualReason?: DnsManualReason;
+    /** With `publication: "conflict"`: why. A server that doesn't say means `not_owned`. */
+    conflictReason?: DnsConflictReason;
+    /** With `conflictReason: "type_mismatch"`: the live records the administrator has to delete. */
+    existing?: DnsExistingRecord[];
+    /** `ownership` only: the token is (still) at the domain's root, where it lived before `_rapidmx-verify.<domain>`. */
+    legacyApex?: boolean;
 }
 export declare function getDnsSetup(uid: string, client?: ApiClient): Promise<DnsRecordCheck[]>;
+/** Assigns the domain to a DNS provider config, or back to manual (`null`). Needs an elevated token; the provider must cover the domain more specifically
+ * than any other (a 400 otherwise). Answers the domain. */
+export declare function assignDnsProvider(uid: string, dnsProviderUid: string | null, client?: ApiClient): Promise<Domain>;
+/** What `GET /:id/apex-txt` answers: the managed state and what the opt-in form starts from. */
+export interface ApexTxtView {
+    managed: boolean;
+    keep: string[];
+    spf?: string;
+    /** The values at the domain's root now, as a live lookup sees them. */
+    current: string[];
+    /** `current` without SPF records and RapidMX ownership tokens: what the list of values to keep starts as. */
+    suggestedKeep: string[];
+    /** The lookup couldn't be answered, so `current` and `suggestedKeep` say nothing about what is there: the opt-in must not be offered. */
+    lookupFailed?: true;
+}
+export declare function getApexTxt(uid: string, client?: ApiClient): Promise<ApexTxtView>;
+/** Opts the domain's root TXT records into RapidMX's management (`managed: true` with the values to keep), edits the kept values while managed, or
+ * opts out (`managed: false`). Needs an elevated token. Answers the domain. */
+export declare function updateApexTxt(uid: string, input: {
+    managed: boolean;
+    keep?: string[];
+}, client?: ApiClient): Promise<Domain>;
+/** Why a DKIM key rotation began: the schedule, an administrator's "Rotate now", or a key reported compromised (no publish wait, no overlap). */
+export type DkimRotationReason = "scheduled" | "manual" | "compromised";
+/** A domain's DKIM key rotation, as `Domain.dkimRotation` holds it. `idle`: none in progress. `pending`: the new key (`next`, whose `publicKey` is `""`
+ * until it is generated) is published and signing waits for it to be live (`liveSince`) and the publish wait to pass. `switching`: signing switched to the
+ * new key (`switchedAt`) and the mail server hasn't confirmed it yet. `overlap`: confirmed; the old key (`previous`) stays published until its
+ * `retireAt`. */
+export interface DkimRotationState {
+    phase: "idle" | "pending" | "switching" | "overlap";
+    next?: {
+        selector: string;
+        publicKey: string;
+        createdAt: string;
+        liveSince?: string;
+        reason: DkimRotationReason;
+    };
+    previous?: {
+        selector: string;
+        publicKey: string;
+        retireAt?: string;
+    };
+    /** The reason of the rotation that switched, kept until it is retired. */
+    reason?: DkimRotationReason;
+    switchedAt?: string;
+    lastRotatedAt?: string;
+    lastCancelledAt?: string;
+    /** Scheduled rotation is paused for this domain. */
+    paused?: boolean;
+    /** What is holding the rotation up: no confirmation from the mail server, a key that couldn't be generated. */
+    lastError?: string;
+}
+/** Why a domain's key can't rotate: the key provider doesn't rotate, outbound mail is signed by SES, the domain has no key yet, or its key was imported by
+ * hand or can't be told from one. */
+export type DkimRotationBlocker = "unsupported" | "ses" | "no_key" | "imported" | "unknown_key";
+/** What `GET /:id/dkim/rotation` answers. */
+export interface DkimRotationView {
+    rotation: DkimRotationState | null;
+    rotatable: boolean;
+    blocker?: DkimRotationBlocker;
+    /** When the next scheduled rotation starts; only while none is in progress, the domain isn't paused and scheduled rotation is on. */
+    nextScheduledAt?: string;
+}
+export declare function getDkimRotation(uid: string, client?: ApiClient): Promise<DkimRotationView>;
+/** Starts a rotation of the domain's DKIM key ("Rotate now"). With `compromised`, the publish wait and the overlap are skipped, and during a rotation it
+ * reports the key being replaced as compromised. Needs an elevated token. Answers the domain. */
+export declare function rotateDkim(uid: string, input?: {
+    compromised?: boolean;
+}, client?: ApiClient): Promise<Domain>;
+/** Abandons a rotation the mail server hasn't confirmed (a switch not yet confirmed is reverted); a 409 once it has. Needs an elevated token. Answers the
+ * domain. */
+export declare function cancelDkimRotation(uid: string, client?: ApiClient): Promise<Domain>;
+/** Pauses or resumes scheduled rotation for the domain; a rotation in progress still finishes. Needs an elevated token. Answers the domain. */
+export declare function setDkimRotationPaused(uid: string, paused: boolean, client?: ApiClient): Promise<Domain>;

package/dist/lib/admin/domainsApi.js

@@ -42,3 +42,36 @@ export function verifyDomain(uid, client) {
 export function getDnsSetup(uid, client) {
     return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/dns-setup`);
 }
+/** Assigns the domain to a DNS provider config, or back to manual (`null`). Needs an elevated token; the provider must cover the domain more specifically
+ * than any other (a 400 otherwise). Answers the domain. */
+export function assignDnsProvider(uid, dnsProviderUid, client) {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/dns-provider`, {
+        method: "PUT",
+        body: JSON.stringify({ dnsProviderUid }),
+    });
+}
+export function getApexTxt(uid, client) {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/apex-txt`);
+}
+/** Opts the domain's root TXT records into RapidMX's management (`managed: true` with the values to keep), edits the kept values while managed, or
+ * opts out (`managed: false`). Needs an elevated token. Answers the domain. */
+export function updateApexTxt(uid, input, client) {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/apex-txt`, { method: "PUT", body: JSON.stringify(input) });
+}
+export function getDkimRotation(uid, client) {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/dkim/rotation`);
+}
+/** Starts a rotation of the domain's DKIM key ("Rotate now"). With `compromised`, the publish wait and the overlap are skipped, and during a rotation it
+ * reports the key being replaced as compromised. Needs an elevated token. Answers the domain. */
+export function rotateDkim(uid, input = {}, client) {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/dkim/rotate`, { method: "POST", body: JSON.stringify(input) });
+}
+/** Abandons a rotation the mail server hasn't confirmed (a switch not yet confirmed is reverted); a 409 once it has. Needs an elevated token. Answers the
+ * domain. */
+export function cancelDkimRotation(uid, client) {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/dkim/rotation/cancel`, { method: "POST" });
+}
+/** Pauses or resumes scheduled rotation for the domain; a rotation in progress still finishes. Needs an elevated token. Answers the domain. */
+export function setDkimRotationPaused(uid, paused, client) {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/dkim/rotation`, { method: "PUT", body: JSON.stringify({ paused }) });
+}

package/dist/lib/admin/integrationsApi.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BaseIntegrationsRoute` (mounted at `system/integrations`): the third-party services an administrator
+ * chooses (Giphy, STUN, the S/MIME signing CA, the DNS resolver, the plugin registry), each section overriding some of the deployment's configuration.
+ * `GET` needs a trusted role; every write a trusted role and an elevated token. Secrets are write-only: the server answers them only as the mask.
+ */
+import { ApiClient } from "../util/api.js";
+/** What the server shows in place of a secret that is set (restapi `SecretMask`); sent back, it means "keep the saved value". `unreadable` is the
+ * server saying that this copy can't decrypt it (a key missing from its keyring, after a restore with an older one): never sent back. */
+export interface SecretMask {
+    secret: true;
+    unreadable?: boolean;
+}
+/** Whether `value` is the mask: an object whose keys are `secret`, set to `true`, and at most `unreadable`, a flag. */
+export declare function isSecretMask(value: unknown): value is SecretMask;
+/** Whether `value` is the mask of a secret that is set but that the server can't read: it must be entered again. */
+export declare function isUnreadableSecret(value: unknown): boolean;
+export type IntegrationSectionName = "giphy" | "stun" | "signingCa" | "dnsResolver" | "pluginRegistry";
+/** Where a field's value comes from: saved by an administrator here, or the deployment's configuration. */
+export type IntegrationSource = "admin" | "deployment";
+/** One section as the server shows it (restapi `IntegrationSectionView`): the values in effect, the deployment's own values (what a reset puts a field
+ * back to) and where each value comes from. A secret is the mask when set, else `null`. */
+export interface IntegrationSectionView<V> {
+    values: V;
+    defaults: V;
+    source: Record<keyof V, IntegrationSource>;
+}
+export interface GiphyIntegration {
+    enabled: boolean;
+    apiKey: SecretMask | null;
+}
+export interface StunIntegration {
+    /** `null`: the meet plugin's built-in list. */
+    urls: string[] | null;
+}
+export type SigningCaBackend = "rfc8823" | "manual" | "none";
+export interface SigningCaIntegration {
+    backend: SigningCaBackend;
+    directoryUrl: string;
+    contactEmail: string | null;
+}
+export type DnsResolverMode = "node" | "doh-dnssec";
+export interface DnsResolverIntegration {
+    mode: DnsResolverMode;
+    dohEndpoint: string;
+}
+/** A plugin namespace as the view shows it: its token only as the mask. Sent back, `token` is the mask (keep), a new value, or left out (none). */
+export interface IntegrationPluginNamespace {
+    name: string;
+    registry?: string;
+    token?: SecretMask | string;
+}
+export interface PluginRegistryIntegration {
+    url: string;
+    token: SecretMask | null;
+    namespaces: IntegrationPluginNamespace[];
+}
+/** What `GET /system/integrations` and every write answer (restapi `IntegrationSettingsResponse`). */
+export interface IntegrationSettings {
+    giphy: IntegrationSectionView<GiphyIntegration>;
+    stun: IntegrationSectionView<StunIntegration>;
+    signingCa: IntegrationSectionView<SigningCaIntegration>;
+    dnsResolver: IntegrationSectionView<DnsResolverIntegration>;
+    pluginRegistry: IntegrationSectionView<PluginRegistryIntegration>;
+    /** The saved settings' version (0 before anything was saved), sent back with a change so one made against an older version is refused (409). */
+    version: number;
+}
+/** A section's change: a field left out is unchanged, `null` puts it back to the deployment's value, a secret sent back as the mask is kept. */
+export type IntegrationSectionPatch = Record<string, unknown> & {
+    version?: number;
+};
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export declare function getIntegrations(client?: ApiClient): Promise<IntegrationSettings>;
+export declare function updateIntegrationSection(section: IntegrationSectionName, patch: IntegrationSectionPatch, client?: ApiClient): Promise<IntegrationSettings>;

package/dist/lib/admin/integrationsApi.js

@@ -0,0 +1,31 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BaseIntegrationsRoute` (mounted at `system/integrations`): the third-party services an administrator
+ * chooses (Giphy, STUN, the S/MIME signing CA, the DNS resolver, the plugin registry), each section overriding some of the deployment's configuration.
+ * `GET` needs a trusted role; every write a trusted role and an elevated token. Secrets are write-only: the server answers them only as the mask.
+ */
+import { withClient } from "../util/api.js";
+/** Whether `value` is the mask: an object whose keys are `secret`, set to `true`, and at most `unreadable`, a flag. */
+export function isSecretMask(value) {
+    if (typeof value !== "object" || value === null || value.secret !== true) {
+        return false;
+    }
+    const unreadable = value.unreadable;
+    return Object.keys(value).length === (unreadable === undefined ? 1 : 2) && (unreadable === undefined || typeof unreadable === "boolean");
+}
+/** Whether `value` is the mask of a secret that is set but that the server can't read: it must be entered again. */
+export function isUnreadableSecret(value) {
+    return isSecretMask(value) && value.unreadable === true;
+}
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export function getIntegrations(client) {
+    return withClient(client, "/system/integrations");
+}
+export function updateIntegrationSection(section, patch, client) {
+    return withClient(client, `/system/integrations/${section}`, { method: "PUT", body: JSON.stringify(patch) });
+}

package/lib/admin/configKeysApi.ts

@@ -0,0 +1,117 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BaseConfigKeyRoute` (mounted at `system/config-keys`): the keyring that encrypts the credentials, API keys and
+ * tokens saved in the console, and the rotation of its keys. `GET` needs a trusted role; both writes a trusted role and an elevated token. Never any key
+ * material: a key is its `kid`, its age and how many values it encrypts.
+ */
+import { ApiClient, ApiRequestError, withClient } from "../util/api.js";
+
+/** Where a rotation is (restapi `ConfigKeyRotationPhase`). */
+export type ConfigKeyRotationPhase = "adding" | "activating" | "reencrypting" | "retiring" | "done" | "failed";
+
+/** One key of the ring (restapi `PublicConfigKey`). */
+export interface ConfigKeyInfo {
+    kid: string;
+    /** ISO 8601. */
+    createdAt: string;
+    /** Whether the server copy that answered encrypts with it. */
+    active: boolean;
+    /** The values encrypted with it at the end of the last re-encryption pass; left out until one has counted. */
+    envelopes?: number;
+}
+
+/** The current or last rotation (restapi `PublicConfigKeyRotation`). */
+export interface ConfigKeyRotation {
+    /** The new key, once it is in the keyring. */
+    kid?: string;
+    /** The keys it replaces. */
+    previousKids: string[];
+    compromised: boolean;
+    requestedBy: string;
+    requestedAt: string;
+    phase: ConfigKeyRotationPhase;
+    activationStartedAt?: string;
+    /** The server copies (pod name and process id) that haven't yet loaded the new key while it is `activating`, and, once activated, those that don't yet
+     * encrypt with it. */
+    waitingFor?: string[];
+    activatedAt?: string;
+    /** Set by "Activate anyway", with the copies that hadn't loaded the key then. */
+    activationForced?: { by: string; at: string; staleCopies: string[] };
+    finishedAt?: string;
+    /** What failed (a keyring write refused, for example), never a value. */
+    lastError?: string;
+    /** Why the new key is still not active and what resolves it, once the wait has gone on past `config_encryption:activation:warn_minutes`. */
+    warning?: string;
+}
+
+/** A saved value the last re-encryption pass couldn't decrypt: named by record and field, never its value. */
+export interface ConfigKeyUnreadable {
+    record: string;
+    uid: string;
+    field: string;
+    /** The key the envelope names. */
+    kid: string;
+}
+
+export interface ConfigKeyReencryption {
+    targetKid: string;
+    /** Whether the last pass saw every row and saved every change. */
+    complete: boolean;
+    startedAt: string;
+    finishedAt?: string;
+    unreadable?: ConfigKeyUnreadable[];
+}
+
+/** The plugin secret settings' encryption (spec 5.7). */
+export interface PluginSecretsState {
+    /** When the first encryption run completed; until then secret settings are saved in plain text. */
+    encryptedAt?: string;
+    waitingForRollout?: boolean;
+    checkedAt?: string;
+    /** Why the run is still waiting (old pods, or the pods can't be listed). */
+    reason?: string;
+}
+
+/** What `GET /system/config-keys` and both writes answer (restapi `PublicConfigKeys`). */
+export interface ConfigKeys {
+    /** Whether a rotation can be started: the keyring is in a store the server can write, and the server copies can be coordinated. */
+    available: boolean;
+    activeKid: string | null;
+    keys: ConfigKeyInfo[];
+    /** When the values were last counted. */
+    countedAt: string | null;
+    rotation: ConfigKeyRotation | null;
+    reencryption: ConfigKeyReencryption | null;
+    pluginSecrets: PluginSecretsState | null;
+}
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export function getConfigKeys(client?: ApiClient): Promise<ConfigKeys> {
+    return withClient(client, "/system/config-keys");
+}
+
+/** Starts a rotation of the configuration key. With `compromised`, it also marks a rotation already running as compromised. Needs an elevated token. A 409
+ * (one is running) carries its progress: see `configKeysOfRefusal()`. */
+export function rotateConfigKey(input: { compromised?: boolean } = {}, client?: ApiClient): Promise<ConfigKeys> {
+    return withClient(client, "/system/config-keys/rotate", { method: "POST", body: JSON.stringify(input) });
+}
+
+/** "Activate anyway": makes the rotation's new key the one that encrypts before every server copy has loaded it. A 409 (the rotation isn't waiting to be
+ * activated, or `kid` isn't its key) carries its progress. Needs an elevated token. */
+export function activateConfigKey(kid: string, client?: ApiClient): Promise<ConfigKeys> {
+    return withClient(client, "/system/config-keys/activate", { method: "POST", body: JSON.stringify({ kid }) });
+}
+
+/** The keyring's state a 409 carries as its body (a rotation already running, or not waiting to be activated), `undefined` for any other failure. */
+export function configKeysOfRefusal(err: unknown): ConfigKeys | undefined {
+    if (!(err instanceof ApiRequestError) || err.status !== 409) {
+        return undefined;
+    }
+    const body = err.details as Partial<ConfigKeys> | null | undefined;
+    return body && typeof body === "object" && Array.isArray(body.keys) ? (body as ConfigKeys) : undefined;
+}

package/lib/admin/dnsProvidersApi.ts

@@ -0,0 +1,241 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BaseDnsProviderRoute` (mounted at `system/dns-providers`): the DNS provider configs the server publishes
+ * domain records through, the provider types the console's form is built from, the operations the DNS controller runs for a config, and what the
+ * controller last said about itself. Reads need a trusted role; every write a trusted role and an elevated token. Credentials are write-only.
+ */
+import { ApiClient, withClient } from "../util/api.js";
+import type { DnsConflictReason, DnsExistingRecord, DnsManualReason, DnsPublicationState, DnsRecordType } from "./domainsApi.js";
+import type { SecretMask } from "./integrationsApi.js";
+
+export type DnsProviderType = "cloudflare" | "route53" | "rfc2136" | "google" | "azure";
+
+export type DnsProviderOptionValue = string | number | boolean | string[];
+
+export type DnsProviderOptionKind = "string" | "string-list" | "integer" | "boolean" | "enum";
+
+/** One non-secret option of a provider type (restapi `DnsProviderTypeInfo["options"]`). */
+export interface DnsProviderOptionSpec {
+    key: string;
+    label: string;
+    kind: DnsProviderOptionKind;
+    required: boolean;
+    /** What a value left out is saved as. */
+    default?: string | number | boolean;
+    /** The choices of an `enum`. */
+    values?: string[];
+    min?: number;
+    max?: number;
+    maxItems?: number;
+    description: string;
+    format?: string;
+}
+
+/** One credential field of a provider type: saved encrypted on the config, never shown again. */
+export interface DnsProviderSecretFieldSpec {
+    key: string;
+    label: string;
+    /** Always needed. One needed only in some configurations says when in `description`. */
+    required: boolean;
+    /** A file's content (Google's service-account JSON) rather than a token. */
+    multiLine?: boolean;
+    description: string;
+    format?: string;
+}
+
+/** What `GET /system/dns-providers/types` answers per type. */
+export interface DnsProviderTypeInfo {
+    type: DnsProviderType;
+    label: string;
+    externalDnsProvider: string;
+    /** Whether the type has been tested against the real service; the console marks the others "not yet live-tested". */
+    tested: boolean;
+    options: DnsProviderOptionSpec[];
+    secretFields: DnsProviderSecretFieldSpec[];
+    unsupportedRecordKinds: ("MX" | "SRV")[];
+    notes: string[];
+}
+
+/** What the DNS controller last reported about a config's external-dns instance; every field optional. */
+export interface DnsProviderStatus {
+    reportedAt?: string;
+    readyReplicas?: number;
+    image?: string;
+    lastRolloutAt?: string;
+    lastSyncAt?: string;
+    registryErrors?: number;
+    sourceErrors?: number;
+    providerErrors?: number;
+    ownerMismatchRecords?: number;
+    lastError?: string;
+}
+
+/** A provider config as the server shows it (restapi `PublicDnsProvider`): its credentials only as masks, one per key saved. */
+export interface DnsProvider {
+    uid: string;
+    name: string;
+    type: DnsProviderType;
+    zones: string[];
+    options: Record<string, DnsProviderOptionValue>;
+    credentials: Record<string, SecretMask>;
+    origin?: "installer" | "console";
+    enabled: boolean;
+    allowTakeover: boolean;
+    status?: DnsProviderStatus;
+    /** The domains assigned to this config. */
+    domainCount: number;
+    version: number;
+    dateCreated?: string;
+    dateModified?: string;
+}
+
+/** What a create or an update sends. `credentials` is write-only: a string sets a field, `null` clears it, leaving it out keeps it. */
+export interface DnsProviderInput {
+    name?: string;
+    /** Create only: a config's type never changes. */
+    type?: DnsProviderType;
+    zones?: string[];
+    options?: Record<string, DnsProviderOptionValue>;
+    credentials?: Record<string, string | null>;
+    enabled?: boolean;
+    allowTakeover?: boolean;
+    /** Update only: the version the change was made against; a newer one is a 409. */
+    version?: number;
+}
+
+export type DnsOperationType = "test" | "takeover" | "restore";
+
+export type DnsOperationState = "queued" | "running" | "succeeded" | "failed";
+
+/** One operation the DNS controller runs for a config (restapi `PublicDnsOperation`). */
+export interface DnsOperation {
+    uid: string;
+    type: DnsOperationType;
+    providerUid: string;
+    domainUid?: string;
+    /** `hosts-<provider uid>` for the takeover of the deployment's own host names, which has no domain. */
+    endpointSetId?: string;
+    state: DnsOperationState;
+    /** The controller's result, or why the operation was cancelled (`Cancelled: ...`). */
+    message?: string;
+    requestedBy?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    dateCreated?: string;
+}
+
+/** What one status report of the controller is remembered by. */
+export interface DnsControllerReport {
+    controllerVersion: string;
+    desiredStateVersion?: number;
+    leaseHolder: boolean;
+    leaseIdentity: string;
+    at: string;
+}
+
+/** What `GET /system/dns-providers/controller` answers: what the DNS controller last said about itself, `null` for what it never said. */
+export interface DnsControllerState {
+    handshake: {
+        controllerVersion: string;
+        apiVersions: string[];
+        compatible: boolean;
+        selected?: string;
+        reason?: string;
+        at: string;
+    } | null;
+    lastReport: DnsControllerReport | null;
+    lastStandbyReport: DnsControllerReport | null;
+}
+
+const BASE = "/system/dns-providers";
+
+/** The path of the config `uid`. */
+function providerPath(uid: string): string {
+    return `${BASE}/${encodeURIComponent(uid)}`;
+}
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export function listDnsProviders(client?: ApiClient): Promise<DnsProvider[]> {
+    return withClient(client, BASE);
+}
+
+export function listDnsProviderTypes(client?: ApiClient): Promise<DnsProviderTypeInfo[]> {
+    return withClient(client, `${BASE}/types`);
+}
+
+export function getDnsControllerState(client?: ApiClient): Promise<DnsControllerState> {
+    return withClient(client, `${BASE}/controller`);
+}
+
+export function getDnsProvider(uid: string, client?: ApiClient): Promise<DnsProvider> {
+    return withClient(client, providerPath(uid));
+}
+
+export function createDnsProvider(input: DnsProviderInput, client?: ApiClient): Promise<DnsProvider> {
+    return withClient(client, BASE, { method: "POST", body: JSON.stringify(input) });
+}
+
+export function updateDnsProvider(uid: string, input: DnsProviderInput, client?: ApiClient): Promise<DnsProvider> {
+    return withClient(client, providerPath(uid), { method: "PUT", body: JSON.stringify(input) });
+}
+
+/** Refused (409) while a domain is assigned to the config or a restore through it is still to run. */
+export function deleteDnsProvider(uid: string, client?: ApiClient): Promise<void> {
+    return withClient(client, providerPath(uid), { method: "DELETE" });
+}
+
+/** Queues a credentials test the DNS controller runs; answers the queued operation. */
+export function testDnsProvider(uid: string, client?: ApiClient): Promise<DnsOperation> {
+    return withClient(client, `${providerPath(uid)}/test`, { method: "POST" });
+}
+
+/** Queues the takeover of a domain's records that this deployment doesn't own yet: the DNS controller overwrites them with the wanted values. `records`
+ * are the record types to take over, all the domain publishes through the config when left out; never the root TXT set (`spf`). Answers the queued
+ * operation. */
+export function takeoverDnsRecords(uid: string, domainUid: string, records?: DnsRecordType[], client?: ApiClient): Promise<DnsOperation> {
+    return withClient(client, `${providerPath(uid)}/takeover`, {
+        method: "POST",
+        body: JSON.stringify({ domainUid, ...(records ? { records } : {}) }),
+    });
+}
+
+/** Queues the takeover of the deployment's own host names (`mail.<domain>`, `auth.<domain>` and the like) that this config publishes and that something
+ * else created: the DNS controller overwrites them with the wanted values. `records` are the host names to take over, all the config publishes when left
+ * out; a host whose records of another type are in the way (`type_mismatch`) is left out, or refused when named. Answers the queued operation. */
+export function takeoverDnsHosts(uid: string, records?: string[], client?: ApiClient): Promise<DnsOperation> {
+    return withClient(client, `${providerPath(uid)}/takeover`, {
+        method: "POST",
+        body: JSON.stringify({ hosts: true, ...(records ? { records } : {}) }),
+    });
+}
+
+/** Why a host name isn't published automatically: a domain record's reasons, or no public address or no mail host to point at. */
+export type DnsHostManualReason = DnsManualReason | "no_addresses" | "no_target";
+
+/** How one record of the deployment's own host names is published (`GET /system/dns-providers/hosts`, restapi `DnsRecordPublication`). */
+export interface DnsHostPublication {
+    type: string;
+    recordName: string;
+    recordKind: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "SRV";
+    state: DnsPublicationState;
+    manualReason?: DnsHostManualReason;
+    conflictReason?: DnsConflictReason;
+    existing?: DnsExistingRecord[];
+    /** The config that publishes it, which a takeover names. */
+    providerUid?: string;
+}
+
+/** The publication of each of the deployment's own host names, looked up live. Needs a trusted role; a server without DNS publishing answers 404. */
+export function listDnsHostPublications(client?: ApiClient): Promise<DnsHostPublication[]> {
+    return withClient(client, `${BASE}/hosts`);
+}
+
+/** The config's latest operations, newest first. */
+export function listDnsProviderOperations(uid: string, client?: ApiClient): Promise<DnsOperation[]> {
+    return withClient(client, `${providerPath(uid)}/operations`);
+}