@gusnips/one-click-dns 0.1.4 → 0.1.5

package/README.md

@@ -159,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/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.
@@ -750,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;
@@ -770,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,

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

@@ -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.
@@ -186,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;
@@ -206,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/one-click-dns",
-  "version": "0.1.4",
+  "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",