@gusnips/one-click-dns 0.1.2 → 0.1.4

package/README.md

@@ -62,17 +62,27 @@ When the write fails, it throws a `DnsWriteError` with a `code`. Word each code
 | `conflict`          | The name already has another record (`params.type`). They decide what to do with it. |
 | `unavailable`       | The host did not answer. Try again.                                                  |
 
-Four hosts have a writer today. What the person pastes is different for each. Every test uses a fake network, so none of them has run against a real account here:
+Four hosts have a writer today. What the person pastes is different for each. The tests use a fake network. Cloudflare and DigitalOcean were also run against a real account, with made-up underscore names that were deleted after. Porkbun and Name.com were not:
 
-| Writer         | `token` is              | What it needs                                                           | How far it is checked                                              |
-| -------------- | ----------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| `cloudflare`   | An API token            | `Zone:Read` and `DNS:Edit`                                              | Lifted from featury's live help-center code                        |
-| `porkbun`      | `apikey:secretapikey`   | "API access" turned on for the domain in Porkbun (it is off by default) | Written from the host's API spec. Never run against a real account |
-| `digitalocean` | A personal access token | `domain:read` and `domain:create`, or full access                       | Written from the host's API spec. Never run against a real account |
-| `name-com`     | `username:apitoken`     | API access turned on in Account Settings, Security                      | Written from the host's docs. Never run against a real account     |
+| Writer         | `token` is              | What it needs                                                           | How far it is checked                                                                     |
+| -------------- | ----------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `cloudflare`   | An API token            | `Zone:Read` and `DNS:Edit`                                              | Run against a real zone on 2026-10-29: create, repeat, TXT, conflicts and a wrong token   |
+| `porkbun`      | `apikey:secretapikey`   | "API access" turned on for the domain in Porkbun (it is off by default) | Written from the host's API spec. Never run against a real account                        |
+| `digitalocean` | A personal access token | `domain:read` and `domain:create`, or full access                       | Run against a real domain on 2026-10-29: create, repeat, TXT, conflicts and a wrong token |
+| `name-com`     | `username:apitoken`     | API access turned on in Account Settings, Security                      | Written from the host's docs. Never run against a real account                            |
 
 `writers` maps a host id to its writer, so `writers[host]` is `undefined` for a host with no writer.
 
+### Check a writer against your own account
+
+The repository has a script that tries a writer on a real zone and removes what it made. Use a spare zone and a token limited to it:
+
+```bash
+HOST=cloudflare ZONE=example.com TOKEN=your-token bun run live
+```
+
+It writes a CNAME and a TXT record under made-up underscore names, runs each a second time (both must read as "unchanged"), checks that a clashing record is refused and that a wrong token is reported as one, then deletes its records. Cloudflare and DigitalOcean are supported.
+
 ## One-click links (Domain Connect)
 
 A link needs a template that your DNS host has switched on, and a key pair. You publish the public key in DNS and keep the private key on your server.
@@ -102,6 +112,8 @@ When the host has your template, `plan.methods` starts with a `domain-connect` m
 
 Only these providers are asked, because their `_domainconnect` value and settings were read from DNS: Cloudflare, Vercel, Simply.com and GoDaddy. A name in a customer's DNS is never fetched. More providers join the same way, one value at a time.
 
+A provider listed here is one the package can talk to. It is not a promise that the provider will switch your template on. GoDaddy, for one, told us on 2026-10-29 that it is not accepting new templates for direct onboarding and gave no date. Ask each provider, and use `templateCoverage` to see who said yes. Where there is no link, `plan.methods` still ends with the steps for that host.
+
 ### Which providers have switched your template on
 
 A merged template is not a template a provider uses. Each provider turns templates on by hand, and the only way to know is to ask it. `templateCoverage` asks every provider in the list once:
@@ -141,6 +153,8 @@ console.log(templateFileName(template)); // "example.com.custom-domain.json"
 
 There are presets for a CNAME, DMARC, SPF, DKIM, MX and a verification TXT.
 
+Two of them change how a domain's email works. The MX preset replaces the MX records the domain has, so its mail goes somewhere else. The SPF preset adds a sender to the domain's SPF record. Ask the person for consent in your own screen before you offer either link, and say what changes in the template's `description`, which the DNS host shows when they approve.
+
 A template belongs to the company that files it. It names your key domain, and the host checks every link against the key published there. So you cannot use someone else's template, and nobody can use yours. The customer's domain is not in the template: it comes with each link, so one template serves every customer.
 
 To file a template: test it in the [online editor](https://domainconnect.paulonet.eu/dc/free/templateedit), run `dc-template-linter -merge-or-fail` on it, open a pull request, then ask each DNS host to switch it on.

package/dist/{chunk-4XNRV7QR.js → chunk-LLWYWMJ5.js}

@@ -81,23 +81,26 @@ var API = "https://api.cloudflare.com/client/v4";
 var TIMEOUT_MS = 1e4;
 var MAX_BODY_BYTES = 256 * 1024;
 var TOKEN_CODES = /* @__PURE__ */ new Set([1e3, 6003, 6111, 1e4]);
+var INVALID_TOKEN_MESSAGE = /invalid access token/i;
 var CONFLICT_CODES = /* @__PURE__ */ new Set([81053, 81054, 81057]);
 var ID = /^[A-Za-z0-9]{1,64}$/;
 var RECORD_TYPE = /^[A-Z0-9]{1,12}$/;
 function readEnvelope(json) {
   if (!isObject(json) || typeof json.success !== "boolean") return null;
   const codes = [];
+  const messages = [];
   if (Array.isArray(json.errors)) {
     for (const error of json.errors) {
       if (!isObject(error)) return null;
       if (typeof error.code === "number") codes.push(error.code);
+      if (typeof error.message === "string") messages.push(error.message);
       if (Array.isArray(error.error_chain)) {
         for (const link of error.error_chain)
           if (isObject(link) && typeof link.code === "number") codes.push(link.code);
       }
     }
   }
-  return { success: json.success, codes, result: json.result };
+  return { success: json.success, codes, messages, result: json.result };
 }
 async function call(doFetch, token, path, send) {
   const res = await fetchBounded(
@@ -124,7 +127,8 @@ async function call(doFetch, token, path, send) {
 }
 function refusal(answer, stage, subject) {
   const codes = answer.body?.codes ?? [];
-  const refusedToken = answer.status === 401 || codes.some((c) => TOKEN_CODES.has(c));
+  const messages = answer.body?.messages ?? [];
+  const refusedToken = answer.status === 401 || codes.some((c) => TOKEN_CODES.has(c)) || messages.some((m) => INVALID_TOKEN_MESSAGE.test(m));
   if (stage === "zones" && refusedToken) return new DnsWriteError("token_invalid");
   if (codes.some((c) => CONFLICT_CODES.has(c)))
     return new DnsWriteError("conflict", { ...subject });

package/dist/index.cjs

@@ -663,21 +663,24 @@ function spfTemplate(identity, options = {}) {
   );
 }
 function dkimTemplate(identity, options = {}) {
-  const keys = options.keys ?? 2;
+  const { selectors } = options;
+  const keys = selectors?.length ?? options.keys ?? 2;
   const numbers = Array.from({ length: keys }, (_, index) => index + 1);
+  const hostOf = (n) => selectors ? `${selectors[n - 1]}._domainkey` : `%selector${n}%._domainkey`;
+  const describe = (n) => selectors ? `%target${n}%: where ${selectors[n - 1]}._domainkey points` : `%selector${n}%: the key name, ${n} of ${keys}; %target${n}%: where it points`;
   return template(
     identity,
     "dkim",
     {
       serviceName: "Sign your email with our key",
       description: "Adds the CNAME records that let us sign email sent from your domain.",
-      variableDescription: numbers.map((n) => `%selector${n}%: the key name, ${n} of ${keys}; %target${n}%: where it points`).join("; ")
+      variableDescription: options.variableDescription ?? numbers.map(describe).join("; ")
     },
     options,
     numbers.map((n) => ({
       type: "CNAME",
-      host: `%selector${n}%._domainkey`,
-      pointsTo: `%target${n}%`,
+      host: hostOf(n),
+      pointsTo: options.pointsTo?.(n) ?? `%target${n}%`,
       ttl: TTL
     }))
   );

package/dist/index.d.cts

@@ -99,12 +99,24 @@ declare function dmarcTemplate(identity: TemplateIdentity, options?: Wording & {
 /** Adds one `include:` to the domain's SPF record. `SPFM` merges it into the one record the
  *  name may have; a TXT would make a second one and break SPF. The link carries `%include%`. */
 declare function spfTemplate(identity: TemplateIdentity, options?: Wording): DomainConnectTemplate;
-/** DKIM as CNAMEs, for services that publish the key on their side. The link carries
- *  `%selector1%` and `%target1%`, then the same pair numbered up to `keys`. */
+/**
+ * DKIM as CNAMEs, for services that publish the key on their side.
+ *
+ * By default the link carries `%selector1%` and `%target1%`, then the same pair numbered up to
+ * `keys`. When your key names never change, fix them: `selectors: ["cd1", "cd2"]` writes
+ * `cd1._domainkey` and `cd2._domainkey` into the template, which the repository prefers to a
+ * variable. `pointsTo` then names where each CNAME goes (`(n) => "%dkim" + n + "%.example.net"`),
+ * and `variableDescription` says what its variables mean.
+ */
 declare function dkimTemplate(identity: TemplateIdentity, options?: Wording & {
     keys?: number;
+    selectors?: readonly string[];
+    pointsTo?: (n: number) => string;
+    variableDescription?: string;
 }): DomainConnectTemplate;
-/** The MX record that sends the domain's mail to you. */
+/** The MX record that sends the domain's mail to you. It changes where the domain's email is
+ *  delivered and replaces the MX records it has, so ask the person for consent before you offer
+ *  the link; say so in `description` too. */
 declare function mxTemplate(identity: TemplateIdentity, options: Wording & {
     pointsTo: string;
     priority?: number;

package/dist/index.d.ts

@@ -99,12 +99,24 @@ declare function dmarcTemplate(identity: TemplateIdentity, options?: Wording & {
 /** Adds one `include:` to the domain's SPF record. `SPFM` merges it into the one record the
  *  name may have; a TXT would make a second one and break SPF. The link carries `%include%`. */
 declare function spfTemplate(identity: TemplateIdentity, options?: Wording): DomainConnectTemplate;
-/** DKIM as CNAMEs, for services that publish the key on their side. The link carries
- *  `%selector1%` and `%target1%`, then the same pair numbered up to `keys`. */
+/**
+ * DKIM as CNAMEs, for services that publish the key on their side.
+ *
+ * By default the link carries `%selector1%` and `%target1%`, then the same pair numbered up to
+ * `keys`. When your key names never change, fix them: `selectors: ["cd1", "cd2"]` writes
+ * `cd1._domainkey` and `cd2._domainkey` into the template, which the repository prefers to a
+ * variable. `pointsTo` then names where each CNAME goes (`(n) => "%dkim" + n + "%.example.net"`),
+ * and `variableDescription` says what its variables mean.
+ */
 declare function dkimTemplate(identity: TemplateIdentity, options?: Wording & {
     keys?: number;
+    selectors?: readonly string[];
+    pointsTo?: (n: number) => string;
+    variableDescription?: string;
 }): DomainConnectTemplate;
-/** The MX record that sends the domain's mail to you. */
+/** The MX record that sends the domain's mail to you. It changes where the domain's email is
+ *  delivered and replaces the MX records it has, so ask the person for consent before you offer
+ *  the link; say so in `description` too. */
 declare function mxTemplate(identity: TemplateIdentity, options: Wording & {
     pointsTo: string;
     priority?: number;

package/dist/index.js

@@ -117,21 +117,24 @@ function spfTemplate(identity, options = {}) {
   );
 }
 function dkimTemplate(identity, options = {}) {
-  const keys = options.keys ?? 2;
+  const { selectors } = options;
+  const keys = selectors?.length ?? options.keys ?? 2;
   const numbers = Array.from({ length: keys }, (_, index) => index + 1);
+  const hostOf = (n) => selectors ? `${selectors[n - 1]}._domainkey` : `%selector${n}%._domainkey`;
+  const describe = (n) => selectors ? `%target${n}%: where ${selectors[n - 1]}._domainkey points` : `%selector${n}%: the key name, ${n} of ${keys}; %target${n}%: where it points`;
   return template(
     identity,
     "dkim",
     {
       serviceName: "Sign your email with our key",
       description: "Adds the CNAME records that let us sign email sent from your domain.",
-      variableDescription: numbers.map((n) => `%selector${n}%: the key name, ${n} of ${keys}; %target${n}%: where it points`).join("; ")
+      variableDescription: options.variableDescription ?? numbers.map(describe).join("; ")
     },
     options,
     numbers.map((n) => ({
       type: "CNAME",
-      host: `%selector${n}%._domainkey`,
-      pointsTo: `%target${n}%`,
+      host: hostOf(n),
+      pointsTo: options.pointsTo?.(n) ?? `%target${n}%`,
       ttl: TTL
     }))
   );

package/dist/server/index.cjs

@@ -647,6 +647,9 @@ var CONNECT_PROVIDERS = [
   // Settings read 2026-10-29 from domainconnect.api.godaddy.com (`urlSyncUX`
   // https://dcc.godaddy.com/manage). The TXT value on a customer's zone is not read yet: if it
   // differs, GoDaddy answers "not offered", which is the safe way to be wrong.
+  // GoDaddy told us on 2026-10-29 that it is "not currently accepting new templates for direct
+  // onboarding", with no timeline. It supports many templates already (9 of 12 third-party ones
+  // we probed), so the entry stays for them, but a template of yours answers "not offered" there.
   {
     id: "godaddy",
     txt: "domainconnect.api.godaddy.com",
@@ -858,23 +861,26 @@ var API = "https://api.cloudflare.com/client/v4";
 var TIMEOUT_MS = 1e4;
 var MAX_BODY_BYTES = 256 * 1024;
 var TOKEN_CODES = /* @__PURE__ */ new Set([1e3, 6003, 6111, 1e4]);
+var INVALID_TOKEN_MESSAGE = /invalid access token/i;
 var CONFLICT_CODES = /* @__PURE__ */ new Set([81053, 81054, 81057]);
 var ID = /^[A-Za-z0-9]{1,64}$/;
 var RECORD_TYPE = /^[A-Z0-9]{1,12}$/;
 function readEnvelope(json) {
   if (!isObject(json) || typeof json.success !== "boolean") return null;
   const codes = [];
+  const messages = [];
   if (Array.isArray(json.errors)) {
     for (const error of json.errors) {
       if (!isObject(error)) return null;
       if (typeof error.code === "number") codes.push(error.code);
+      if (typeof error.message === "string") messages.push(error.message);
       if (Array.isArray(error.error_chain)) {
         for (const link of error.error_chain)
           if (isObject(link) && typeof link.code === "number") codes.push(link.code);
       }
     }
   }
-  return { success: json.success, codes, result: json.result };
+  return { success: json.success, codes, messages, result: json.result };
 }
 async function call(doFetch, token, path, send) {
   const res = await fetchBounded(
@@ -901,7 +907,8 @@ async function call(doFetch, token, path, send) {
 }
 function refusal(answer, stage, subject) {
   const codes = answer.body?.codes ?? [];
-  const refusedToken = answer.status === 401 || codes.some((c) => TOKEN_CODES.has(c));
+  const messages = answer.body?.messages ?? [];
+  const refusedToken = answer.status === 401 || codes.some((c) => TOKEN_CODES.has(c)) || messages.some((m) => INVALID_TOKEN_MESSAGE.test(m));
   if (stage === "zones" && refusedToken) return new DnsWriteError("token_invalid");
   if (codes.some((c) => CONFLICT_CODES.has(c)))
     return new DnsWriteError("conflict", { ...subject });

package/dist/server/index.js

@@ -5,7 +5,7 @@ import {
   fetchBounded,
   isObject,
   writers
-} from "../chunk-4XNRV7QR.js";
+} from "../chunk-LLWYWMJ5.js";
 import {
   normalizeDnsName
 } from "../chunk-P2O7INDB.js";
@@ -112,6 +112,9 @@ var CONNECT_PROVIDERS = [
   // Settings read 2026-10-29 from domainconnect.api.godaddy.com (`urlSyncUX`
   // https://dcc.godaddy.com/manage). The TXT value on a customer's zone is not read yet: if it
   // differs, GoDaddy answers "not offered", which is the safe way to be wrong.
+  // GoDaddy told us on 2026-10-29 that it is "not currently accepting new templates for direct
+  // onboarding", with no timeline. It supports many templates already (9 of 12 third-party ones
+  // we probed), so the entry stays for them, but a template of yours answers "not offered" there.
   {
     id: "godaddy",
     txt: "domainconnect.api.godaddy.com",

package/dist/writers/index.cjs

@@ -113,23 +113,26 @@ var API = "https://api.cloudflare.com/client/v4";
 var TIMEOUT_MS = 1e4;
 var MAX_BODY_BYTES = 256 * 1024;
 var TOKEN_CODES = /* @__PURE__ */ new Set([1e3, 6003, 6111, 1e4]);
+var INVALID_TOKEN_MESSAGE = /invalid access token/i;
 var CONFLICT_CODES = /* @__PURE__ */ new Set([81053, 81054, 81057]);
 var ID = /^[A-Za-z0-9]{1,64}$/;
 var RECORD_TYPE = /^[A-Z0-9]{1,12}$/;
 function readEnvelope(json) {
   if (!isObject(json) || typeof json.success !== "boolean") return null;
   const codes = [];
+  const messages = [];
   if (Array.isArray(json.errors)) {
     for (const error of json.errors) {
       if (!isObject(error)) return null;
       if (typeof error.code === "number") codes.push(error.code);
+      if (typeof error.message === "string") messages.push(error.message);
       if (Array.isArray(error.error_chain)) {
         for (const link of error.error_chain)
           if (isObject(link) && typeof link.code === "number") codes.push(link.code);
       }
     }
   }
-  return { success: json.success, codes, result: json.result };
+  return { success: json.success, codes, messages, result: json.result };
 }
 async function call(doFetch, token, path, send) {
   const res = await fetchBounded(
@@ -156,7 +159,8 @@ async function call(doFetch, token, path, send) {
 }
 function refusal(answer, stage, subject) {
   const codes = answer.body?.codes ?? [];
-  const refusedToken = answer.status === 401 || codes.some((c) => TOKEN_CODES.has(c));
+  const messages = answer.body?.messages ?? [];
+  const refusedToken = answer.status === 401 || codes.some((c) => TOKEN_CODES.has(c)) || messages.some((m) => INVALID_TOKEN_MESSAGE.test(m));
   if (stage === "zones" && refusedToken) return new DnsWriteError("token_invalid");
   if (codes.some((c) => CONFLICT_CODES.has(c)))
     return new DnsWriteError("conflict", { ...subject });

package/dist/writers/index.js

@@ -5,7 +5,7 @@ import {
   namecom,
   porkbun,
   writers
-} from "../chunk-4XNRV7QR.js";
+} from "../chunk-LLWYWMJ5.js";
 import "../chunk-P2O7INDB.js";
 export {
   DnsWriteError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/one-click-dns",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "packageManager": "bun@1.4.2",
   "description": "Put DNS records in a customer's zone: find their DNS host, send them to a signed Domain Connect link, write with an API token, or show the steps for that host",
   "type": "module",
@@ -47,9 +47,10 @@
   "scripts": {
     "build": "tsup src/index.ts src/server/index.ts src/writers/index.ts --format cjs,esm --dts --clean",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src",
+    "lint": "eslint src scripts",
     "format": "prettier --write .",
     "test": "bun test",
+    "live": "bun scripts/live-check.ts",
     "prepublishOnly": "bun run lint && bun run typecheck && bun run build"
   },
   "keywords": [