@gusnips/one-click-dns 0.1.3 → 0.1.5

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:
@@ -147,6 +159,39 @@ A template belongs to the company that files it. It names your key domain, and t
 
 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.
 
+### Keep separate SPF services
+
+Two links for the same template can replace each other's records, even if you check DNS before issuing either link. For SPF, that can remove another service's permission to send.
+
+When one template serves several sending services, opt in to separate instances:
+
+```ts
+const template = spfTemplate(identity, { multiInstance: true, version: 2 });
+```
+
+File the updated template and wait for the DNS provider to switch it on. Before signing a link, require that provider's copy to advertise the flag:
+
+```ts
+import { discoverConnect, systemDnsLookups } from "@gusnips/one-click-dns/server";
+
+const discovery = await discoverConnect(
+  { txt: systemDnsLookups(2000).txt },
+  {
+    zone: "acme.com",
+    providerId: "example.com",
+    serviceId: "spf",
+    budgetMs: 2000,
+    requireMultiInstance: true,
+  },
+);
+```
+
+This check needs both a provider entry with `supportsMultiInstance: true` and the literal template flag `multiInstance: true`. Missing or false support returns `not_offered`. The template check reads the same size-limited response and makes no extra request. Other discovery calls keep their current behavior.
+
+No built-in provider has verified instance support yet. [Cloudflare says it ignores this flag](https://developers.cloudflare.com/dns/reference/domain-connect/#template-definition); the other providers are unverified. Requiring instances therefore returns `not_offered` for each built-in provider. Keep a manual fallback. For a custom `providers` list, set `supportsMultiInstance: true` only after verifying that provider's behavior, not just its template JSON.
+
+Only sign when `discovery.found` is true. The signed sync link carries the template flag; the spec defines `instanceId` for the async apply and revert, not for the sync parameters. If you later remove one application through the async API, pass a stable `instanceId` derived from the full sending domain and the service's SPF include: the same pair reuses the same id, and different domains or services use different ids. The package does not choose that id for you. The flag does not check SPF's lookup limit or make a redirect back to your app proof that DNS changed.
+
 ## Steps for the host
 
 `DNS_HOSTS` holds 33 hosts: how to recognise them from their name servers, the labels on their DNS page and the traps (a proxy on by default, a trailing dot, a TXT that needs quotes). The package holds data and no sentences, so you write the steps in your own words and languages. `dnsRecordRow` spells a record the way a host wants it typed:

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

@@ -606,6 +606,7 @@ function template(identity, serviceId, fallback, wording, records, hostRequired)
     syncPubKeyDomain: identity.syncPubKeyDomain,
     syncRedirectDomain: identity.syncRedirectDomain,
     ...hostRequired ? { hostRequired } : {},
+    ...wording.multiInstance !== void 0 ? { multiInstance: wording.multiInstance } : {},
     records
   };
 }

package/dist/index.d.cts

@@ -70,14 +70,17 @@ interface DomainConnectTemplate extends TemplateIdentity {
     variableDescription?: string;
     /** The subdomain is required: the template has no meaning at the name itself. */
     hostRequired?: boolean;
+    /** Tell a stateful provider that a re-apply must not remove earlier applications. */
+    multiInstance?: boolean;
     records: TemplateRecord[];
 }
-/** What every preset lets the app word itself. */
+/** What every preset lets the app choose. */
 interface Wording {
     serviceId?: string;
     serviceName?: string;
     description?: string;
     version?: number;
+    multiInstance?: boolean;
 }
 /** The `<providerId>.<serviceId>.json` name the Templates repository files it under. */
 declare function templateFileName(t: Pick<DomainConnectTemplate, "providerId" | "serviceId">): string;

package/dist/index.d.ts

@@ -70,14 +70,17 @@ interface DomainConnectTemplate extends TemplateIdentity {
     variableDescription?: string;
     /** The subdomain is required: the template has no meaning at the name itself. */
     hostRequired?: boolean;
+    /** Tell a stateful provider that a re-apply must not remove earlier applications. */
+    multiInstance?: boolean;
     records: TemplateRecord[];
 }
-/** What every preset lets the app word itself. */
+/** What every preset lets the app choose. */
 interface Wording {
     serviceId?: string;
     serviceName?: string;
     description?: string;
     version?: number;
+    multiInstance?: boolean;
 }
 /** The `<providerId>.<serviceId>.json` name the Templates repository files it under. */
 declare function templateFileName(t: Pick<DomainConnectTemplate, "providerId" | "serviceId">): string;

package/dist/index.js

@@ -60,6 +60,7 @@ function template(identity, serviceId, fallback, wording, records, hostRequired)
     syncPubKeyDomain: identity.syncPubKeyDomain,
     syncRedirectDomain: identity.syncRedirectDomain,
     ...hostRequired ? { hostRequired } : {},
+    ...wording.multiInstance !== void 0 ? { multiInstance: wording.multiInstance } : {},
     records
   };
 }

package/dist/server/index.cjs

@@ -627,7 +627,10 @@ var CONNECT_PROVIDERS = [
     id: "cloudflare",
     txt: "api.cloudflare.com/client/v4/dns/domainconnect",
     api: "https://api.cloudflare.com/client/v4/dns/domainconnect",
-    syncHost: "dash.cloudflare.com"
+    syncHost: "dash.cloudflare.com",
+    // Cloudflare documents this flag as unsupported and ignored:
+    // https://developers.cloudflare.com/dns/reference/domain-connect/#template-definition
+    supportsMultiInstance: false
   },
   // `_domainconnect.nextjs.org` read 2026-10-29: a CNAME to `_domainconnect.vercel-dns.com`, whose
   // TXT is `domainconnect.vercel.com`. The settings name another address for the API.
@@ -647,6 +650,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",
@@ -747,6 +753,7 @@ async function ask(io, args, deadline) {
   const values = published.txts.map(normalizeTxt);
   const provider = providers.find((entry) => values.includes(entry.txt));
   if (!provider) return NOT_OFFERED;
+  if (args.requireMultiInstance && provider.supportsMultiInstance !== true) return NOT_OFFERED;
   const settings = await get(`https://${provider.txt}/v2/${zone}/settings`);
   if (!settings) return UNANSWERED;
   if (settings.status !== 200) return transient(settings.status) ? UNANSWERED : NOT_OFFERED;
@@ -767,6 +774,15 @@ async function ask(io, args, deadline) {
   );
   if (!template) return UNANSWERED;
   if (template.status !== 200) return transient(template.status) ? UNANSWERED : NOT_OFFERED;
+  if (args.requireMultiInstance) {
+    let templateBody;
+    try {
+      templateBody = JSON.parse(template.text);
+    } catch {
+      return NOT_OFFERED;
+    }
+    if (!isObject(templateBody) || templateBody.multiInstance !== true) return NOT_OFFERED;
+  }
   return {
     found: true,
     id: provider.id,
@@ -858,23 +874,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 +920,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.d.cts

@@ -52,6 +52,8 @@ interface ConnectProvider {
     api: string;
     /** The one host the settings' `urlSyncUX` may name: the page we send the person's browser to. */
     syncHost: string;
+    /** Verified support for separate template instances. Omitted means unverified. */
+    supportsMultiInstance?: boolean;
 }
 declare const CONNECT_PROVIDERS: readonly ConnectProvider[];
 
@@ -81,6 +83,10 @@ declare function discoverConnect(io: DiscoveryIo, args: {
     providerId: string;
     serviceId: string;
     budgetMs: number;
+    /** Require verified provider support and template JSON with `multiInstance: true`.
+     *  Callers that later remove one application through the async API must pass a
+     *  stable instanceId for each independent service application. */
+    requireMultiInstance?: boolean;
     providers?: readonly ConnectProvider[];
 }): Promise<Discovery>;
 

package/dist/server/index.d.ts

@@ -52,6 +52,8 @@ interface ConnectProvider {
     api: string;
     /** The one host the settings' `urlSyncUX` may name: the page we send the person's browser to. */
     syncHost: string;
+    /** Verified support for separate template instances. Omitted means unverified. */
+    supportsMultiInstance?: boolean;
 }
 declare const CONNECT_PROVIDERS: readonly ConnectProvider[];
 
@@ -81,6 +83,10 @@ declare function discoverConnect(io: DiscoveryIo, args: {
     providerId: string;
     serviceId: string;
     budgetMs: number;
+    /** Require verified provider support and template JSON with `multiInstance: true`.
+     *  Callers that later remove one application through the async API must pass a
+     *  stable instanceId for each independent service application. */
+    requireMultiInstance?: boolean;
     providers?: readonly ConnectProvider[];
 }): Promise<Discovery>;
 

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";
@@ -92,7 +92,10 @@ var CONNECT_PROVIDERS = [
     id: "cloudflare",
     txt: "api.cloudflare.com/client/v4/dns/domainconnect",
     api: "https://api.cloudflare.com/client/v4/dns/domainconnect",
-    syncHost: "dash.cloudflare.com"
+    syncHost: "dash.cloudflare.com",
+    // Cloudflare documents this flag as unsupported and ignored:
+    // https://developers.cloudflare.com/dns/reference/domain-connect/#template-definition
+    supportsMultiInstance: false
   },
   // `_domainconnect.nextjs.org` read 2026-10-29: a CNAME to `_domainconnect.vercel-dns.com`, whose
   // TXT is `domainconnect.vercel.com`. The settings name another address for the API.
@@ -112,6 +115,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",
@@ -183,6 +189,7 @@ async function ask(io, args, deadline) {
   const values = published.txts.map(normalizeTxt);
   const provider = providers.find((entry) => values.includes(entry.txt));
   if (!provider) return NOT_OFFERED;
+  if (args.requireMultiInstance && provider.supportsMultiInstance !== true) return NOT_OFFERED;
   const settings = await get(`https://${provider.txt}/v2/${zone}/settings`);
   if (!settings) return UNANSWERED;
   if (settings.status !== 200) return transient(settings.status) ? UNANSWERED : NOT_OFFERED;
@@ -203,6 +210,15 @@ async function ask(io, args, deadline) {
   );
   if (!template) return UNANSWERED;
   if (template.status !== 200) return transient(template.status) ? UNANSWERED : NOT_OFFERED;
+  if (args.requireMultiInstance) {
+    let templateBody;
+    try {
+      templateBody = JSON.parse(template.text);
+    } catch {
+      return NOT_OFFERED;
+    }
+    if (!isObject(templateBody) || templateBody.multiInstance !== true) return NOT_OFFERED;
+  }
   return {
     found: true,
     id: provider.id,

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.3",
+  "version": "0.1.5",
   "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": [