@gusnips/one-click-dns 0.0.0-stage → 0.1.0

package/dist/server/index.d.cts

@@ -0,0 +1,144 @@
+import { Resolver } from 'node:dns/promises';
+import { h as DnsZone, e as DnsHostReading, D as DnsHostId } from '../hosts-B0_V4Ned.cjs';
+
+/** What one question came back with. `absent` is DNS answering that nothing is there; `failed`
+ *  is DNS not answering, which must never read as absent. */
+type DnsAnswer<T> = T | "absent" | "failed";
+/** Ask one question of a Resolver the caller does not own. */
+type DnsAsk = <T>(question: (resolver: Resolver) => Promise<T>) => Promise<DnsAnswer<T>>;
+/**
+ * A Resolver of its own (one try per question), and the way to ask it: each question is bounded
+ * by `timeoutMs` whatever the runtime's own resolver does with its timeout option (Node waits
+ * up to twice as long). The bound gives up on a question; it does not cancel it, which is why
+ * this Resolver is never shared with a caller that needs `cancel()`.
+ */
+declare function systemResolver(timeoutMs: number): DnsAsk;
+/** The questions the package asks: the TXT records of a name, one CNAME hop, a name's NS. */
+interface DnsLookups {
+    txt(name: string): Promise<DnsAnswer<{
+        txts: string[];
+    }>>;
+    cname(name: string): Promise<DnsAnswer<{
+        name: string;
+    }>>;
+    ns(name: string): Promise<DnsAnswer<{
+        names: string[];
+    }>>;
+}
+/** The system resolver, each question bounded by `timeoutMs`. */
+declare function systemDnsLookups(timeoutMs: number): DnsLookups;
+
+type ZoneLookups = Pick<DnsLookups, "cname" | "ns">;
+/** The reading for a zone read from DNS. The host is worked out here, on every read, so a stored
+ *  zone follows the table when a pattern is added. */
+declare function dnsHostOf(zone: DnsZone): DnsHostReading;
+/**
+ * The nearest zone at or above `hostname` that has name servers of its own, or `null` when DNS
+ * did not answer, no name up the tree has any, or the walk ran past `budgetMs`. A slow resolver
+ * costs the caller its budget and no more.
+ */
+declare function readDnsZone(lookups: ZoneLookups, hostname: string, budgetMs: number): Promise<DnsZone | null>;
+
+interface ConnectProvider {
+    /** Our id for the provider. */
+    id: string;
+    /** The whole `_domainconnect` TXT value: host and path, no scheme, no trailing slash, as the
+     *  reference library reads it (`https://<value>/v2/<zone>/settings`). Not just the host, so a
+     *  path of a customer's choosing on an allowed host is refused as well. */
+    txt: string;
+    /** The `urlAPI` the settings must name, `https://` and no trailing slash: where the template
+     *  check goes. It is the TXT's own address for most providers, not for all. */
+    api: string;
+    /** The one host the settings' `urlSyncUX` may name: the page we send the person's browser to. */
+    syncHost: string;
+}
+declare const CONNECT_PROVIDERS: readonly ConnectProvider[];
+
+interface DiscoveryIo {
+    txt: DnsLookups["txt"];
+    fetch?: typeof fetch;
+}
+type Discovery = {
+    found: true;
+    /** Our id for the provider (`cloudflare`). */
+    id: string;
+    /** The provider's own name for itself, as its settings give it. */
+    provider: string;
+    /** `urlSyncUX`, without a trailing slash: where the apply path goes. */
+    syncUrl: string;
+} | {
+    found: false;
+    reason: "not_offered" | "unanswered";
+};
+/**
+ * The provider that can add `serviceId` to `zone`, or why none can. `budgetMs` covers all three
+ * questions together; a lookup still running when it ends is left behind.
+ */
+declare function discoverConnect(io: DiscoveryIo, args: {
+    zone: string;
+    /** The provider id our templates are filed under (`DomainConnectIdentity.providerId`). */
+    providerId: string;
+    serviceId: string;
+    budgetMs: number;
+    providers?: readonly ConnectProvider[];
+}): Promise<Discovery>;
+
+/** Who is asking, as the templates name it. */
+interface DomainConnectIdentity {
+    /** The provider id our templates are filed under in the Templates repository
+     *  (`<providerId>.<serviceId>.json`). Use a domain that will not be renamed. */
+    providerId: string;
+    /** The label of the TXT record that holds our public key (`_dck1`), the template's
+     *  `syncPubKeyDomain` hosts it. A new key is a new id and a release. */
+    keyId: string;
+}
+/**
+ * The page to send the person to: `syncUrl` is the provider's `urlSyncUX`, `params` the
+ * template's own (`domain`, `host`, its variables) and `redirect_uri`. Signed with the private
+ * key (a PEM), whose public half is the TXT record `keyId` names. `key` and `sig` always come
+ * last, in that order.
+ */
+declare function signedApplyUrl(args: DomainConnectIdentity & {
+    syncUrl: string;
+    serviceId: string;
+    params: Readonly<Record<string, string>>;
+    privateKeyPem: string;
+}): string;
+
+type ConnectMethod = {
+    kind: "domain-connect";
+    /** The provider's own name for itself: "Cloudflare". */
+    provider: string;
+    /** The signed page to send the person's browser to. */
+    url: string;
+} | {
+    kind: "api-token";
+    host: DnsHostId;
+} | {
+    kind: "manual";
+    hosts: DnsHostId[];
+};
+interface ConnectPlan {
+    /** Where the domain's DNS lives; null when DNS didn't answer, never an empty reading. */
+    reading: DnsHostReading | null;
+    /** Best first. Ends with `manual`. */
+    methods: ConnectMethod[];
+    /** Domain Connect asked and got no answer in time: worth asking again. */
+    connectUnanswered: boolean;
+}
+interface PlanInput {
+    hostname: string;
+    /** Offer a Domain Connect link for one of the app's templates. Left out: none is offered. */
+    connect?: DomainConnectIdentity & {
+        serviceId: string;
+        privateKeyPem: string;
+        /** The template's parameters for this zone: `domain`, `host`, its variables and
+         *  `redirect_uri`. The app owns them. */
+        params: (zone: string) => Record<string, string>;
+    };
+    /** Time for the zone read, and the same again for Domain Connect. Default 3 000. */
+    budgetMs?: number;
+}
+declare function planConnection(input: PlanInput, io: DiscoveryIo & ZoneLookups): Promise<ConnectPlan>;
+
+export { CONNECT_PROVIDERS, type ConnectMethod, type ConnectPlan, type ConnectProvider, type Discovery, type DiscoveryIo, type DnsAnswer, type DnsAsk, type DnsLookups, type DomainConnectIdentity, type PlanInput, type ZoneLookups, discoverConnect, dnsHostOf, planConnection, readDnsZone, signedApplyUrl, systemDnsLookups, systemResolver };

package/dist/server/index.d.ts

@@ -0,0 +1,144 @@
+import { Resolver } from 'node:dns/promises';
+import { h as DnsZone, e as DnsHostReading, D as DnsHostId } from '../hosts-B0_V4Ned.js';
+
+/** What one question came back with. `absent` is DNS answering that nothing is there; `failed`
+ *  is DNS not answering, which must never read as absent. */
+type DnsAnswer<T> = T | "absent" | "failed";
+/** Ask one question of a Resolver the caller does not own. */
+type DnsAsk = <T>(question: (resolver: Resolver) => Promise<T>) => Promise<DnsAnswer<T>>;
+/**
+ * A Resolver of its own (one try per question), and the way to ask it: each question is bounded
+ * by `timeoutMs` whatever the runtime's own resolver does with its timeout option (Node waits
+ * up to twice as long). The bound gives up on a question; it does not cancel it, which is why
+ * this Resolver is never shared with a caller that needs `cancel()`.
+ */
+declare function systemResolver(timeoutMs: number): DnsAsk;
+/** The questions the package asks: the TXT records of a name, one CNAME hop, a name's NS. */
+interface DnsLookups {
+    txt(name: string): Promise<DnsAnswer<{
+        txts: string[];
+    }>>;
+    cname(name: string): Promise<DnsAnswer<{
+        name: string;
+    }>>;
+    ns(name: string): Promise<DnsAnswer<{
+        names: string[];
+    }>>;
+}
+/** The system resolver, each question bounded by `timeoutMs`. */
+declare function systemDnsLookups(timeoutMs: number): DnsLookups;
+
+type ZoneLookups = Pick<DnsLookups, "cname" | "ns">;
+/** The reading for a zone read from DNS. The host is worked out here, on every read, so a stored
+ *  zone follows the table when a pattern is added. */
+declare function dnsHostOf(zone: DnsZone): DnsHostReading;
+/**
+ * The nearest zone at or above `hostname` that has name servers of its own, or `null` when DNS
+ * did not answer, no name up the tree has any, or the walk ran past `budgetMs`. A slow resolver
+ * costs the caller its budget and no more.
+ */
+declare function readDnsZone(lookups: ZoneLookups, hostname: string, budgetMs: number): Promise<DnsZone | null>;
+
+interface ConnectProvider {
+    /** Our id for the provider. */
+    id: string;
+    /** The whole `_domainconnect` TXT value: host and path, no scheme, no trailing slash, as the
+     *  reference library reads it (`https://<value>/v2/<zone>/settings`). Not just the host, so a
+     *  path of a customer's choosing on an allowed host is refused as well. */
+    txt: string;
+    /** The `urlAPI` the settings must name, `https://` and no trailing slash: where the template
+     *  check goes. It is the TXT's own address for most providers, not for all. */
+    api: string;
+    /** The one host the settings' `urlSyncUX` may name: the page we send the person's browser to. */
+    syncHost: string;
+}
+declare const CONNECT_PROVIDERS: readonly ConnectProvider[];
+
+interface DiscoveryIo {
+    txt: DnsLookups["txt"];
+    fetch?: typeof fetch;
+}
+type Discovery = {
+    found: true;
+    /** Our id for the provider (`cloudflare`). */
+    id: string;
+    /** The provider's own name for itself, as its settings give it. */
+    provider: string;
+    /** `urlSyncUX`, without a trailing slash: where the apply path goes. */
+    syncUrl: string;
+} | {
+    found: false;
+    reason: "not_offered" | "unanswered";
+};
+/**
+ * The provider that can add `serviceId` to `zone`, or why none can. `budgetMs` covers all three
+ * questions together; a lookup still running when it ends is left behind.
+ */
+declare function discoverConnect(io: DiscoveryIo, args: {
+    zone: string;
+    /** The provider id our templates are filed under (`DomainConnectIdentity.providerId`). */
+    providerId: string;
+    serviceId: string;
+    budgetMs: number;
+    providers?: readonly ConnectProvider[];
+}): Promise<Discovery>;
+
+/** Who is asking, as the templates name it. */
+interface DomainConnectIdentity {
+    /** The provider id our templates are filed under in the Templates repository
+     *  (`<providerId>.<serviceId>.json`). Use a domain that will not be renamed. */
+    providerId: string;
+    /** The label of the TXT record that holds our public key (`_dck1`), the template's
+     *  `syncPubKeyDomain` hosts it. A new key is a new id and a release. */
+    keyId: string;
+}
+/**
+ * The page to send the person to: `syncUrl` is the provider's `urlSyncUX`, `params` the
+ * template's own (`domain`, `host`, its variables) and `redirect_uri`. Signed with the private
+ * key (a PEM), whose public half is the TXT record `keyId` names. `key` and `sig` always come
+ * last, in that order.
+ */
+declare function signedApplyUrl(args: DomainConnectIdentity & {
+    syncUrl: string;
+    serviceId: string;
+    params: Readonly<Record<string, string>>;
+    privateKeyPem: string;
+}): string;
+
+type ConnectMethod = {
+    kind: "domain-connect";
+    /** The provider's own name for itself: "Cloudflare". */
+    provider: string;
+    /** The signed page to send the person's browser to. */
+    url: string;
+} | {
+    kind: "api-token";
+    host: DnsHostId;
+} | {
+    kind: "manual";
+    hosts: DnsHostId[];
+};
+interface ConnectPlan {
+    /** Where the domain's DNS lives; null when DNS didn't answer, never an empty reading. */
+    reading: DnsHostReading | null;
+    /** Best first. Ends with `manual`. */
+    methods: ConnectMethod[];
+    /** Domain Connect asked and got no answer in time: worth asking again. */
+    connectUnanswered: boolean;
+}
+interface PlanInput {
+    hostname: string;
+    /** Offer a Domain Connect link for one of the app's templates. Left out: none is offered. */
+    connect?: DomainConnectIdentity & {
+        serviceId: string;
+        privateKeyPem: string;
+        /** The template's parameters for this zone: `domain`, `host`, its variables and
+         *  `redirect_uri`. The app owns them. */
+        params: (zone: string) => Record<string, string>;
+    };
+    /** Time for the zone read, and the same again for Domain Connect. Default 3 000. */
+    budgetMs?: number;
+}
+declare function planConnection(input: PlanInput, io: DiscoveryIo & ZoneLookups): Promise<ConnectPlan>;
+
+export { CONNECT_PROVIDERS, type ConnectMethod, type ConnectPlan, type ConnectProvider, type Discovery, type DiscoveryIo, type DnsAnswer, type DnsAsk, type DnsLookups, type DomainConnectIdentity, type PlanInput, type ZoneLookups, discoverConnect, dnsHostOf, planConnection, readDnsZone, signedApplyUrl, systemDnsLookups, systemResolver };

package/dist/server/index.js

@@ -0,0 +1,274 @@
+import {
+  detectDnsHosts
+} from "../chunk-2T2PEF4H.js";
+import {
+  fetchBounded,
+  isObject,
+  writers
+} from "../chunk-FGM7S7GQ.js";
+import {
+  normalizeDnsName
+} from "../chunk-P2O7INDB.js";
+
+// src/server/dns.ts
+import { Resolver } from "dns/promises";
+var ABSENT_CODES = /* @__PURE__ */ new Set(["ENOTFOUND", "ENODATA"]);
+var errorCode = (error) => typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+function systemResolver(timeoutMs) {
+  const resolver = new Resolver({ timeout: timeoutMs, tries: 1 });
+  return async (question) => {
+    let timer;
+    try {
+      return await Promise.race([
+        question(resolver),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => {
+            reject(new Error("DNS lookup timed out"));
+          }, timeoutMs);
+        })
+      ]);
+    } catch (error) {
+      return ABSENT_CODES.has(errorCode(error)) ? "absent" : "failed";
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+function systemDnsLookups(timeoutMs) {
+  const ask2 = systemResolver(timeoutMs);
+  return {
+    async txt(name) {
+      const answer = await ask2((resolver) => resolver.resolveTxt(name));
+      return typeof answer === "string" ? answer : { txts: answer.map((parts) => parts.join("")) };
+    },
+    async cname(name) {
+      const answer = await ask2((resolver) => resolver.resolveCname(name));
+      if (typeof answer === "string") return answer;
+      const first = answer[0];
+      return first ? { name: first } : "absent";
+    },
+    async ns(name) {
+      const answer = await ask2((resolver) => resolver.resolveNs(name));
+      return typeof answer === "string" ? answer : { names: answer };
+    }
+  };
+}
+
+// src/server/zone.ts
+function dnsHostOf(zone) {
+  return { ...zone, hosts: detectDnsHosts(zone.nameservers) };
+}
+async function readDnsZone(lookups, hostname, budgetMs) {
+  let timer;
+  const outOfTime = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), budgetMs);
+  });
+  try {
+    return await Promise.race([walk(lookups, hostname), outOfTime]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function walk(lookups, hostname) {
+  const labels = normalizeDnsName(hostname).split(".");
+  for (let start = 0; start < labels.length - 1; start++) {
+    const zone = labels.slice(start).join(".");
+    const answer = await lookups.ns(zone);
+    if (answer === "failed") return null;
+    if (answer === "absent" || !answer.names.length) continue;
+    const alias = await lookups.cname(zone);
+    if (alias === "failed") return null;
+    if (alias !== "absent") continue;
+    return { zone, nameservers: [...new Set(answer.names.map(normalizeDnsName))].sort() };
+  }
+  return null;
+}
+
+// src/server/connect/providers.ts
+var CONNECT_PROVIDERS = [
+  // `_domainconnect.colding.app` read 2026-10-29; settings answer `urlSyncUX`
+  // https://dash.cloudflare.com/domainconnect.
+  {
+    id: "cloudflare",
+    txt: "api.cloudflare.com/client/v4/dns/domainconnect",
+    api: "https://api.cloudflare.com/client/v4/dns/domainconnect",
+    syncHost: "dash.cloudflare.com"
+  },
+  // `_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.
+  {
+    id: "vercel",
+    txt: "domainconnect.vercel.com",
+    api: "https://vercel.com/api/domain-connect",
+    syncHost: "vercel.com"
+  },
+  // `_domainconnect.simply.com` read 2026-10-29.
+  {
+    id: "simply",
+    txt: "domainconnect.simply.com",
+    api: "https://domainconnect.simply.com",
+    syncHost: "domainconnect.simply.com"
+  },
+  // 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.
+  {
+    id: "godaddy",
+    txt: "domainconnect.api.godaddy.com",
+    api: "https://domainconnect.api.godaddy.com",
+    syncHost: "dcc.godaddy.com"
+  }
+];
+
+// src/server/connect/discover.ts
+var MAX_ANSWER_BYTES = 64 * 1024;
+var NOT_OFFERED = { found: false, reason: "not_offered" };
+var UNANSWERED = { found: false, reason: "unanswered" };
+var ZONE = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+var text = (value, max) => typeof value === "string" && value.length <= max ? value : void 0;
+function readSettings(body) {
+  if (!isObject(body)) return null;
+  const providerName = text(body.providerName, 100);
+  const urlAPI = text(body.urlAPI, 512);
+  if (!providerName || !urlAPI) return null;
+  return {
+    providerName,
+    providerDisplayName: text(body.providerDisplayName, 100),
+    urlSyncUX: text(body.urlSyncUX, 512),
+    urlAPI
+  };
+}
+var normalizeTxt = (value) => value.trim().replace(/^"+|"+$/g, "").trim().toLowerCase().replace(/\/+$/, "");
+function plainHttps(raw) {
+  try {
+    const url = new URL(raw);
+    const plain = url.protocol === "https:" && !url.username && !url.password && !url.port;
+    return plain ? url : null;
+  } catch {
+    return null;
+  }
+}
+var withoutTrailingSlash = (url) => `${url.origin}${url.pathname}`.replace(/\/+$/, "");
+var transient = (status) => status === 429 || status >= 500;
+async function discoverConnect(io, args) {
+  if (!ZONE.test(args.zone)) return NOT_OFFERED;
+  const deadline = Date.now() + args.budgetMs;
+  let timer;
+  const outOfTime = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(UNANSWERED), args.budgetMs);
+  });
+  try {
+    return await Promise.race([ask(io, args, deadline), outOfTime]);
+  } catch {
+    return UNANSWERED;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function ask(io, args, deadline) {
+  const { zone, providerId, serviceId, providers = CONNECT_PROVIDERS } = args;
+  const get = (url) => {
+    const left = deadline - Date.now();
+    if (left <= 0) return Promise.resolve(null);
+    return fetchBounded(
+      io.fetch ?? fetch,
+      url,
+      { method: "GET", headers: { Accept: "application/json" } },
+      { timeoutMs: left, maxBytes: MAX_ANSWER_BYTES }
+    );
+  };
+  const published = await io.txt(`_domainconnect.${zone}`);
+  if (published === "failed") return UNANSWERED;
+  if (published === "absent") return NOT_OFFERED;
+  const values = published.txts.map(normalizeTxt);
+  const provider = providers.find((entry) => values.includes(entry.txt));
+  if (!provider) 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;
+  let body;
+  try {
+    body = JSON.parse(settings.text);
+  } catch {
+    return NOT_OFFERED;
+  }
+  const parsed = readSettings(body);
+  if (!parsed) return NOT_OFFERED;
+  const api = plainHttps(parsed.urlAPI);
+  const sync = parsed.urlSyncUX ? plainHttps(parsed.urlSyncUX) : null;
+  if (!api || withoutTrailingSlash(api) !== provider.api) return NOT_OFFERED;
+  if (!sync || sync.hostname !== provider.syncHost || sync.search || sync.hash) return NOT_OFFERED;
+  const template = await get(
+    `${provider.api}/v2/domainTemplates/providers/${providerId}/services/${serviceId}`
+  );
+  if (!template) return UNANSWERED;
+  if (template.status !== 200) return transient(template.status) ? UNANSWERED : NOT_OFFERED;
+  return {
+    found: true,
+    id: provider.id,
+    provider: parsed.providerDisplayName?.trim() || parsed.providerName,
+    syncUrl: withoutTrailingSlash(sync)
+  };
+}
+
+// src/server/connect/sign.ts
+import { createPrivateKey, sign } from "crypto";
+var encode = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`).replace(/%20/g, "+");
+function signedApplyUrl(args) {
+  const query = Object.entries(args.params).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, value]) => `${encode(name)}=${encode(value)}`).join("&");
+  const signature = sign(
+    "sha256",
+    Buffer.from(query, "utf8"),
+    createPrivateKey(args.privateKeyPem)
+  ).toString("base64");
+  const path = `/v2/domainTemplates/providers/${args.providerId}/services/${args.serviceId}/apply`;
+  return `${args.syncUrl}${path}?${query}&key=${args.keyId}&sig=${encode(signature)}`;
+}
+
+// src/server/plan.ts
+async function planConnection(input, io) {
+  const budgetMs = input.budgetMs ?? 3e3;
+  const zone = await readDnsZone(io, input.hostname, budgetMs);
+  if (!zone)
+    return { reading: null, methods: [{ kind: "manual", hosts: [] }], connectUnanswered: false };
+  const reading = dnsHostOf(zone);
+  const methods = [];
+  let connectUnanswered = false;
+  const { connect } = input;
+  if (connect) {
+    const found = await discoverConnect(io, {
+      zone: zone.zone,
+      providerId: connect.providerId,
+      serviceId: connect.serviceId,
+      budgetMs
+    });
+    if (found.found)
+      methods.push({
+        kind: "domain-connect",
+        provider: found.provider,
+        url: signedApplyUrl({
+          providerId: connect.providerId,
+          keyId: connect.keyId,
+          serviceId: connect.serviceId,
+          privateKeyPem: connect.privateKeyPem,
+          syncUrl: found.syncUrl,
+          params: connect.params(zone.zone)
+        })
+      });
+    else connectUnanswered = found.reason === "unanswered";
+  }
+  const [only, ...others] = reading.hosts;
+  if (only && !others.length && writers[only]) methods.push({ kind: "api-token", host: only });
+  methods.push({ kind: "manual", hosts: reading.hosts });
+  return { reading, methods, connectUnanswered };
+}
+export {
+  CONNECT_PROVIDERS,
+  discoverConnect,
+  dnsHostOf,
+  planConnection,
+  readDnsZone,
+  signedApplyUrl,
+  systemDnsLookups,
+  systemResolver
+};