@aoxborrow/registrar-client 0.9.2 → 0.10.0

package/README.md

@@ -231,7 +231,7 @@ not a claim of available API endpoints. See [101domain](docs/registrars/101domai
   it can't be returned synchronously.
 - **ʲ** Dynadot and NameSilo forward the whole domain (a single `@` rule);
   clearing a forward restores the default nameservers.
-- **ᵏ** Gandi web redirects are subdomain-only — the apex (`@`) is rejected.
+- **ᵏ** Gandi web redirects are per host, apex included; creating one replaces the host's DNS record.
 - **ˡ** GoDaddy domain forwarding uses the v2 customer-scoped API, so it requires
   a `customerId` (the customer UUID, or a numeric shopper ID the client resolves to
   the UUID via an sso-key-only lookup); the old v1 forwarding route was removed.
@@ -273,10 +273,13 @@ Two opt-in extended capabilities cover forwarding, both modelled as replace-all
 sets:
 
 - **Domain (URL) forwarding** — `getDomainForwarding` / `setDomainForwarding`
-  take `DomainForward[]` (`{ host, url, type }`). `host` is apex-relative (`@`,
-  `www`, …); `type` is `temporary` (302) or `permanent` (301). HTTPS targets work
-  wherever the provider issues a certificate for the domain (all supported
-  providers do).
+  take `DomainForward[]` (`{ host, url, type, https? }`). `host` is apex-relative
+  (`@`, `www`, …); `type` is `temporary` (302) or `permanent` (301). The target's
+  scheme is part of `url`. `https` is whether the _source_ host answers on HTTPS
+  (`off` / `on` / `only`, where `only` also redirects HTTP to HTTPS). Only Gandi
+  sets it per rule; Cloudflare is always `on`; other providers manage it
+  themselves, leave it unset on read, and reject an explicit value. Unset on
+  write keeps a rule's current mode.
 - **Email forwarding** — `getEmailForwarding` / `setEmailForwarding` take
   `EmailForward[]` (`{ alias, forwardTo }`). `alias` is the local part; `*` (or
   `@`) is the catch-all. This is alias→inbox **forwarding**, not mailbox hosting.

package/dist/index.cjs

@@ -204,12 +204,18 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 var MASKED_FORWARD_UNSUPPORTED = 'masked/framed forwarding is not supported by this library; use "temporary" or "permanent"';
-function settableForwards(forwards) {
+function settableForwards(forwards, httpsModes = []) {
   for (const f of forwards) {
     if (f.type === "masked") throw new Error(MASKED_FORWARD_UNSUPPORTED);
+    if (f.https !== void 0 && !httpsModes.includes(f.https)) {
+      throw new Error(unsupportedForwardHttps(f.https, httpsModes));
+    }
   }
   return forwards;
 }
+function unsupportedForwardHttps(mode, httpsModes = []) {
+  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");
+}
 function requireConsent(provider, consent) {
   if (!consent) {
     throw new ConsentRequiredError(
@@ -1270,7 +1276,7 @@ var CloudflareRegistrar = class _CloudflareRegistrar extends BaseRegistrar {
    */
   async setDomainForwarding(domainName, forwards, opts) {
     try {
-      const settable = settableForwards(forwards);
+      const settable = settableForwards(forwards, ["on"]);
       const zone = await this.requireZone(domainName, opts);
       const existing = await this.getRedirectRuleset(zone.id, opts);
       if (settable.length === 0) {
@@ -2128,6 +2134,8 @@ var Domain101Registrar = class extends BaseRegistrar {
       throw new ConfigurationError(
         "101domain: only one permanent apex forwarding rule is supported"
       );
+    if (forwards[0]?.https !== void 0)
+      throw new ConfigurationError(`101domain: ${unsupportedForwardHttps(forwards[0].https)}`);
     if (forwards.length) {
       let url;
       try {
@@ -3068,6 +3076,16 @@ var GANDI_TYPE_TO_FORWARD = {
   cloak: "masked"
   // read-only; setDomainForwarding rejects it
 };
+var GANDI_PROTOCOL = {
+  off: "http",
+  on: "https",
+  only: "httpsonly"
+};
+var GANDI_PROTOCOL_TO_HTTPS = {
+  http: "off",
+  https: "on",
+  httpsonly: "only"
+};
 var GandiRegistrar = class extends BaseRegistrar {
   name = "gandi";
   // a REST API: GET and HEAD never change state
@@ -3082,7 +3100,7 @@ var GandiRegistrar = class extends BaseRegistrar {
   static 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 extendedFeatures = [
@@ -3452,73 +3470,128 @@ var GandiRegistrar = class 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 -> `@`).
    */
   async getDomainForwarding(domainName, opts) {
-    const redirs = await this.http.request({
-      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.
+   *
+   * 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.
    *
-   * Gandi only supports forwarding a subdomain, not the apex; an apex host ("@")
-   * throws rather than silently failing with a 500 from the API.
+   * `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).
    */
   async setDomainForwarding(domainName, forwards, opts) {
+    const applied = [];
     try {
-      const settable = settableForwards(forwards);
+      const settable = settableForwards(forwards, ["off", "on", "only"]);
+      const desired = /* @__PURE__ */ new Map();
       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 = await this.getDomainForwarding(domainName, opts);
-      const same = (a, b) => a.host === b.host && a.url === b.url && a.type === b.type;
-      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 current = /* @__PURE__ */ new Map();
+      for (const r of await this.listWebredirs(domainName, opts)) {
+        current.set(gandiFqdnToHost(r.host ?? domainName, domainName), r);
+      }
+      const writes = [];
+      const webredirPath = (host) => `/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;
         }
-      }
-      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).
+        const now = fromGandiWebredir(existing, domainName);
+        const httpsSame = f.https === void 0 || f.https === now.https;
+        if (now.url === f.url && now.type === f.type && httpsSame) continue;
+        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: {
-              host: gandiHostToFqdn(f.host, domainName),
               type: GANDI_FORWARD_TYPE[f.type],
-              url: f.url
+              url: f.url,
+              ...protocol ? { protocol } : {}
             },
             ...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) {
       return { success: false, message: toRegistrarError(error).message };
     }
   }
+  async listWebredirs(domainName, opts) {
+    const redirs = await this.http.request({
+      path: `/domain/domains/${domainName}/webredirs`,
+      ...opts
+    });
+    return redirs ?? [];
+  }
   async setAutoRenew(domainName, enabled, opts) {
     try {
       await this.http.request({
@@ -3706,6 +3779,18 @@ function gandiFqdnToHost(fqdn, domain) {
   const suffix = `.${domain}`;
   return fqdn.endsWith(suffix) ? fqdn.slice(0, -suffix.length) : fqdn;
 }
+function normalizeForwardHost(host) {
+  return host ? host : "@";
+}
+function fromGandiWebredir(r, domain) {
+  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) {
   if (!c) return void 0;
   return {
@@ -8486,6 +8571,7 @@ exports.settableForwards = settableForwards;
 exports.sleep = sleep;
 exports.toDnsEntry = toDnsEntry;
 exports.toRegistrarError = toRegistrarError;
+exports.unsupportedForwardHttps = unsupportedForwardHttps;
 exports.useLabelMapper = useLabelMapper;
 exports.wasNotSent = wasNotSent;
 //# sourceMappingURL=index.cjs.map