@aoxborrow/registrar-client 0.9.2 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aoxborrow/registrar-client",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "One consistent, fully-typed TypeScript interface to many domain registrar APIs (GoDaddy, Cloudflare, Namecheap, Spaceship, Dynadot, Porkbun, and more) behind a single pluggable multi-provider client",
   "author": {
     "name": "Aaron Oxborrow",
@@ -100,7 +100,7 @@
     "eslint-plugin-import-x": "^4.17.1",
     "globals": "^17.12.0",
     "prettier": "^3.9.8",
-    "tsup": "^8.5.0",
+    "tsup": "^9.0.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.71.1",
     "vitest": "^4.1.11"

package/src/registrars/cloudflare.ts

@@ -575,7 +575,8 @@ export class CloudflareRegistrar extends BaseRegistrar {
     opts?: RequestOptions
   ): Promise<OperationResult> {
     try {
-      const settable = settableForwards(forwards); // reject masked before any write
+      // reject masked before any write; HTTPS is always on (Universal SSL)
+      const settable = settableForwards(forwards, ['on']);
       const zone = await this.requireZone(domainName, opts);
       const existing = await this.getRedirectRuleset(zone.id, opts);
 

package/src/registrars/domain101.ts

@@ -26,7 +26,7 @@ import type {
   RequestOptions,
   TldPricing,
 } from '../types';
-import { createDomain, filterDomains, normalizeDomain } from '../utils';
+import { createDomain, filterDomains, normalizeDomain, unsupportedForwardHttps } from '../utils';
 
 // 101domain Client API 1.1.0, https://api.101domain.com/api/documentation
 interface Envelope<T> {
@@ -516,6 +516,8 @@ export class Domain101Registrar extends BaseRegistrar {
       throw new ConfigurationError(
         '101domain: only one permanent apex forwarding rule is supported'
       );
+    if (forwards[0]?.https !== undefined)
+      throw new ConfigurationError(`101domain: ${unsupportedForwardHttps(forwards[0].https)}`);
     if (forwards.length) {
       let url: URL;
       try {

package/src/registrars/gandi.ts

@@ -8,6 +8,7 @@ import type {
   Domain,
   DomainAvailability,
   DomainForward,
+  DomainForwardHttps,
   DomainForwardType,
   DsRecord,
   EmailForward,
@@ -20,7 +21,12 @@ import type {
   TransferDomainInput,
 } from '../types';
 import { REST_SAFE_METHODS } from '../http';
-import { createDomain, filterDomains, settableForwards } from '../utils';
+import {
+  createDomain,
+  filterDomains,
+  settableForwards,
+  type SettableDomainForward,
+} from '../utils';
 import { toRegistrarError } from '../errors';
 import { BaseRegistrar, selectBaseUrl } from '../registrar';
 import { Feature, type RegistrarFeature } from '../features';
@@ -130,7 +136,8 @@ interface GandiForward {
 
 // a web-forwarding (URL redirect) entry from GET
 // /v5/domain/domains/{fqdn}/webredirs. `host` is the full FQDN of the source
-// subdomain; `type` is Gandi's redirect kind (http301/http302/cloak).
+// host (the bare domain for the apex); `type` is Gandi's redirect kind
+// (http301/http302/cloak); `protocol` is http/https/httpsonly.
 interface GandiWebredir {
   host?: string;
   type?: string;
@@ -148,6 +155,17 @@ const GANDI_TYPE_TO_FORWARD: Record<string, DomainForwardType> = {
   http302: 'temporary',
   cloak: 'masked', // read-only; setDomainForwarding rejects it
 };
+// map our DomainForwardHttps to Gandi's webredir `protocol`, and back.
+const GANDI_PROTOCOL: Record<DomainForwardHttps, string> = {
+  off: 'http',
+  on: 'https',
+  only: 'httpsonly',
+};
+const GANDI_PROTOCOL_TO_HTTPS: Record<string, DomainForwardHttps> = {
+  http: 'off',
+  https: 'on',
+  httpsonly: 'only',
+};
 
 /**
  * Gandi.net Registrar
@@ -176,7 +194,7 @@ export class GandiRegistrar extends BaseRegistrar {
   static readonly supportsSandbox = true;
   // On top of core: transfer-out auth code (`authinfo`), DNSSEC read/disable
   // (LiveDNS keys), email forwarding, and web/URL forwarding (webredirs;
-  // per-subdomain, no apex). Note core `setPrivacy` disabling is a no-op for
+  // per host, apex included). Note core `setPrivacy` disabling is a no-op for
   // individual (natural-person) registrants — Gandi keeps WHOIS obfuscation on
   // for GDPR regardless of the request.
   static readonly extendedFeatures: readonly RegistrarFeature[] = [
@@ -605,79 +623,132 @@ export class GandiRegistrar extends BaseRegistrar {
 
   /**
    * Read web/URL forwarding via GET /domain/domains/{fqdn}/webredirs. Gandi keys
-   * each redirect by the full FQDN of the source subdomain; we normalize that back
-   * to a host relative to the apex (e.g. `shop.example.com` -> `shop`).
+   * each redirect by the full FQDN of the source host; we normalize that back to
+   * a host relative to the apex (e.g. `shop.example.com` -> `shop`, and the bare
+   * domain -> `@`).
    */
   override async getDomainForwarding(
     domainName: string,
     opts?: RequestOptions
   ): Promise<DomainForward[]> {
-    const redirs = await this.http.request<GandiWebredir[]>({
-      path: `/domain/domains/${domainName}/webredirs`,
-      ...opts,
-    });
-    return (redirs ?? []).map(r => ({
-      host: gandiFqdnToHost(r.host ?? domainName, domainName),
-      url: r.url ?? '',
-      type: GANDI_TYPE_TO_FORWARD[(r.type ?? '').toLowerCase()] ?? 'permanent',
-    }));
+    const redirs = await this.listWebredirs(domainName, opts);
+    return redirs.map(r => fromGandiWebredir(r, domainName));
   }
 
   /**
-   * Replace web/URL forwarding (full replace; empty clears). Gandi's webredirs
-   * endpoint has no update — only create (POST) and delete (DELETE by FQDN) — so
-   * this diffs against the current set: delete entries that are gone or changed,
-   * then create the desired ones that aren't already present identically.
+   * Replace web/URL forwarding (full replace; empty clears). Diffs against the
+   * current webredirs by host:
+   * - a host that's new is created (POST),
+   * - a host whose url/type/https changed is updated in place (PATCH); with
+   *   `https` unset it keeps the rule's existing `protocol`, so an https
+   *   forward stays https,
+   * - a host that's no longer wanted is deleted (DELETE),
+   * - an identical rule (apex included) is left untouched.
+   * Creates and updates run before any delete, so a failure part-way never leaves
+   * a host that was meant to keep forwarding without a rule. A failure after some
+   * writes landed is reported as a partial update listing what was applied.
    *
-   * Gandi only supports forwarding a subdomain, not the apex; an apex host ("@")
-   * throws rather than silently failing with a 500 from the API.
+   * The apex (`@`) is the bare domain FQDN. Creating a redirect needs Gandi's own
+   * DNS record at the source host, and the apex nearly always has one already
+   * (POST then fails with an opaque 500), so creates send `override: true` to
+   * let Gandi replace the host's record — forwarding the host is the point.
+   *
+   * `https` maps to Gandi's `protocol` (off=http, on=https, only=httpsonly).
+   * A new rule with `https` unset omits `protocol`, so Gandi applies its
+   * default (http). Asking for https makes Gandi provision a Let's Encrypt
+   * certificate for the source host; production does this, but the sandbox
+   * can't (it 500s). Gandi repoints the host at its https redirector at once,
+   * and that refuses the host until the certificate exists, so switching a
+   * live rule to https can leave it unreachable for a while (see gandi.md).
    */
   override async setDomainForwarding(
     domainName: string,
     forwards: DomainForward[],
     opts?: RequestOptions
   ): Promise<OperationResult> {
+    const applied: string[] = [];
     try {
-      const settable = settableForwards(forwards); // reject masked before any write
+      // reject masked before any write
+      const settable = settableForwards(forwards, ['off', 'on', 'only']);
+      const desired = new Map<string, SettableDomainForward>();
       for (const f of settable) {
-        if (!f.host || f.host === '@') {
-          throw new Error(
-            `${this.name}: web forwarding requires a subdomain host; Gandi cannot forward the apex ("@")`
-          );
+        const host = normalizeForwardHost(f.host);
+        if (desired.has(host)) {
+          throw new Error(`${this.name}: duplicate web forwarding host "${host}"`);
         }
+        desired.set(host, { ...f, host });
+      }
+      const current = new Map<string, GandiWebredir>();
+      for (const r of await this.listWebredirs(domainName, opts)) {
+        current.set(gandiFqdnToHost(r.host ?? domainName, domainName), r);
       }
-      const current = await this.getDomainForwarding(domainName, opts);
-      const same = (a: DomainForward, b: DomainForward): boolean =>
-        a.host === b.host && a.url === b.url && a.type === b.type;
 
-      // delete current entries that are no longer wanted, or whose url/type changed
-      for (const existing of current) {
-        if (!settable.some(f => same(f, existing))) {
-          await this.http.request({
-            method: 'DELETE',
-            path: `/domain/domains/${domainName}/webredirs/${gandiHostToFqdn(existing.host, domainName)}`,
-            ...opts,
+      const writes: { label: string; run: () => Promise<unknown> }[] = [];
+      const webredirPath = (host: string): string =>
+        `/domain/domains/${domainName}/webredirs/${gandiHostToFqdn(host, domainName)}`;
+      for (const [host, f] of desired) {
+        const existing = current.get(host);
+        if (!existing) {
+          writes.push({
+            label: `create ${host}`,
+            run: () =>
+              this.http.request({
+                method: 'POST',
+                path: `/domain/domains/${domainName}/webredirs`,
+                body: {
+                  host: gandiHostToFqdn(host, domainName),
+                  type: GANDI_FORWARD_TYPE[f.type],
+                  url: f.url,
+                  ...(f.https ? { protocol: GANDI_PROTOCOL[f.https] } : {}),
+                  override: true,
+                },
+                ...opts,
+              }),
           });
+          continue;
         }
+        const now = fromGandiWebredir(existing, domainName);
+        const httpsSame = f.https === undefined || f.https === now.https;
+        if (now.url === f.url && now.type === f.type && httpsSame) continue; // unchanged
+        const protocol = f.https ? GANDI_PROTOCOL[f.https] : existing.protocol;
+        writes.push({
+          label: `update ${host}`,
+          run: () =>
+            this.http.request({
+              method: 'PATCH',
+              path: webredirPath(host),
+              body: {
+                type: GANDI_FORWARD_TYPE[f.type],
+                url: f.url,
+                ...(protocol ? { protocol } : {}),
+              },
+              ...opts,
+            }),
+        });
       }
-      // create desired entries that aren't already present identically
-      for (const f of settable) {
-        if (!current.some(c => same(c, f))) {
-          await this.http.request({
-            method: 'POST',
-            path: `/domain/domains/${domainName}/webredirs`,
-            // `protocol` is intentionally omitted so Gandi applies its default
-            // (http). Requesting `https` makes Gandi provision a Let's Encrypt
-            // certificate for the source host, which our normalized model doesn't
-            // express (and which the sandbox can't do — it 500s).
-            body: {
-              host: gandiHostToFqdn(f.host, domainName),
-              type: GANDI_FORWARD_TYPE[f.type],
-              url: f.url,
-            },
-            ...opts,
-          });
+      for (const host of current.keys()) {
+        if (desired.has(host)) continue;
+        writes.push({
+          label: `delete ${host}`,
+          run: () => this.http.request({ method: 'DELETE', path: webredirPath(host), ...opts }),
+        });
+      }
+
+      for (const w of writes) {
+        try {
+          await w.run();
+        } catch (error) {
+          if (applied.length === 0) throw error;
+          const rest = writes.slice(applied.length + 1).map(x => x.label);
+          return {
+            success: false,
+            message:
+              `Domain forwarding partially updated: ${w.label} failed ` +
+              `(${toRegistrarError(error).message}); applied: ${applied.join(', ')}` +
+              (rest.length ? `; not attempted: ${rest.join(', ')}` : ''),
+          };
         }
+        applied.push(w.label);
       }
       return { success: true, message: 'Domain forwarding updated successfully' };
     } catch (error) {
@@ -685,6 +756,14 @@ export class GandiRegistrar extends BaseRegistrar {
     }
   }
 
+  private async listWebredirs(domainName: string, opts?: RequestOptions): Promise<GandiWebredir[]> {
+    const redirs = await this.http.request<GandiWebredir[]>({
+      path: `/domain/domains/${domainName}/webredirs`,
+      ...opts,
+    });
+    return redirs ?? [];
+  }
+
   override async setAutoRenew(
     domainName: string,
     enabled: boolean,
@@ -928,6 +1007,19 @@ function gandiFqdnToHost(fqdn: string, domain: string): string {
   const suffix = `.${domain}`;
   return fqdn.endsWith(suffix) ? fqdn.slice(0, -suffix.length) : fqdn;
 }
+// our apex spelling: an empty host also means the apex.
+function normalizeForwardHost(host: string): string {
+  return host ? host : '@';
+}
+function fromGandiWebredir(r: GandiWebredir, domain: string): DomainForward {
+  const https = GANDI_PROTOCOL_TO_HTTPS[(r.protocol ?? '').toLowerCase()];
+  return {
+    host: gandiFqdnToHost(r.host ?? domain, domain),
+    url: r.url ?? '',
+    type: GANDI_TYPE_TO_FORWARD[(r.type ?? '').toLowerCase()] ?? 'permanent',
+    ...(https ? { https } : {}),
+  };
+}
 
 function fromGandiContact(c: GandiContact | undefined): Contact | undefined {
   if (!c) return undefined;

package/src/types.ts

@@ -295,6 +295,14 @@ export interface EmailForward {
 //                 it at all, so the library never creates one.
 export type DomainForwardType = 'temporary' | 'permanent' | 'masked';
 
+// Whether the forward's SOURCE host answers on HTTPS (the provider holds a
+// certificate for it); the destination's scheme is part of `url`.
+//   off  — HTTP only.
+//   on   — HTTP and HTTPS.
+//   only — HTTPS, with HTTP requests redirected to HTTPS.
+// Only some providers let you choose; see `DomainForward.https`.
+export type DomainForwardHttps = 'off' | 'on' | 'only';
+
 // A URL/domain forwarding rule: requests to `host` at the domain are redirected
 // to `url`.
 export interface DomainForward {
@@ -305,6 +313,12 @@ export interface DomainForward {
   url: string;
   // the redirect style
   type: DomainForwardType;
+  // source-host HTTPS mode, when the provider exposes it per rule (Gandi; on
+  // Cloudflare it is always 'on'). Reads leave it unset when the provider has no
+  // such setting. On write, unset keeps the rule's current mode (or the
+  // provider's default for a new rule); a value the provider can't apply is
+  // rejected before any write.
+  https?: DomainForwardHttps;
 }
 
 // A DNSSEC delegation-signer (DS) record published at the parent zone. Fields

package/src/utils.ts

@@ -1,5 +1,6 @@
 import type {
   DomainForward,
+  DomainForwardHttps,
   Domain,
   DomainInput,
   RegistrationConsent,
@@ -18,16 +19,35 @@ export type SettableDomainForward = DomainForward & { type: 'temporary' | 'perma
 export const MASKED_FORWARD_UNSUPPORTED =
   'masked/framed forwarding is not supported by this library; use "temporary" or "permanent"';
 
-// Guard for `setDomainForwarding`: reject any masked/framed forward up front (so
-// no partial write happens) and narrow the list to the settable types. Providers
-// call this before writing.
-export function settableForwards(forwards: DomainForward[]): SettableDomainForward[] {
+// Guard for `setDomainForwarding`: reject any masked/framed forward, and any
+// `https` mode outside `httpsModes` (what the provider can apply), up front (so
+// no partial write happens), and narrow the list to the settable types.
+// Providers call this before writing.
+export function settableForwards(
+  forwards: DomainForward[],
+  httpsModes: readonly DomainForwardHttps[] = []
+): SettableDomainForward[] {
   for (const f of forwards) {
     if (f.type === 'masked') throw new Error(MASKED_FORWARD_UNSUPPORTED);
+    if (f.https !== undefined && !httpsModes.includes(f.https)) {
+      throw new Error(unsupportedForwardHttps(f.https, httpsModes));
+    }
   }
   return forwards as SettableDomainForward[];
 }
 
+export function unsupportedForwardHttps(
+  mode: DomainForwardHttps,
+  httpsModes: readonly DomainForwardHttps[] = []
+): string {
+  return (
+    `forwarding https "${mode}" can't be set on this provider` +
+    (httpsModes.length
+      ? ` (supported: ${httpsModes.map(m => `"${m}"`).join(', ')})`
+      : '; leave `https` unset to use its default')
+  );
+}
+
 // guard for register/transfer: registration forms a legal contract with the
 // registry, so a provider must be given explicit consent. Throws
 // ConsentRequiredError (distinct from NotImplementedError) when it's absent.