@rapidmx/web-client 0.37.1 → 0.38.1

package/lib/admin/domainsApi.ts

@@ -31,6 +31,24 @@ 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
@@ -90,7 +108,36 @@ export function verifyDomain(uid: string, client?: ApiClient): Promise<Domain> {
     return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/verify`, { method: "POST" });
 }
 
-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
@@ -106,8 +153,105 @@ 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 function getDnsSetup(uid: string, client?: ApiClient): Promise<DnsRecordCheck[]> {
     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: string, dnsProviderUid: string | null, client?: ApiClient): Promise<Domain> {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/dns-provider`, {
+        method: "PUT",
+        body: JSON.stringify({ dnsProviderUid }),
+    });
+}
+
+/** 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 function getApexTxt(uid: string, client?: ApiClient): Promise<ApexTxtView> {
+    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: string, input: { managed: boolean; keep?: string[] }, client?: ApiClient): Promise<Domain> {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/apex-txt`, { method: "PUT", body: JSON.stringify(input) });
+}
+
+/** 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 function getDkimRotation(uid: string, client?: ApiClient): Promise<DkimRotationView> {
+    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: string, input: { compromised?: boolean } = {}, client?: ApiClient): Promise<Domain> {
+    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: string, client?: ApiClient): Promise<Domain> {
+    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: string, paused: boolean, client?: ApiClient): Promise<Domain> {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/dkim/rotation`, { method: "PUT", body: JSON.stringify({ paused }) });
+}

package/lib/admin/integrationsApi.ts

@@ -0,0 +1,107 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { ApiClient, withClient } 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 function isSecretMask(value: unknown): value is SecretMask {
+    if (typeof value !== "object" || value === null || (value as SecretMask).secret !== true) {
+        return false;
+    }
+    const unreadable: unknown = (value as SecretMask).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: unknown): boolean {
+    return isSecretMask(value) && value.unreadable === true;
+}
+
+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 function getIntegrations(client?: ApiClient): Promise<IntegrationSettings> {
+    return withClient(client, "/system/integrations");
+}
+
+export function updateIntegrationSection(section: IntegrationSectionName, patch: IntegrationSectionPatch, client?: ApiClient): Promise<IntegrationSettings> {
+    return withClient(client, `/system/integrations/${section}`, { method: "PUT", body: JSON.stringify(patch) });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rapidmx/web-client",
-  "version": "0.37.1",
+  "version": "0.38.1",
   "description": "RapidMX's webmail and admin console React UI for web-based clients.",
   "type": "module",
   "repository": "https://github.com/rapidmx/web-client",