ninepm 0.69.0 → 0.78.0

package/dist/domain-state.d.ts

@@ -0,0 +1,147 @@
+export declare const CUSTOM_DOMAIN_EXPIRED_MESSAGE = "This domain was removed because its DNS verification was never completed. Add the domain again to retry.";
+/** The name the CLI has always exported the expired marker under. */
+export declare const CUSTOM_DOMAIN_EXPIRED_TEXT = "This domain was removed because its DNS verification was never completed. Add the domain again to retry.";
+export declare const CUSTOM_DOMAINS_SERVICE_MODE_MESSAGE = "Custom domains are not available for service-token apps, so this domain's hostname was removed. Switching the app to another access mode sets it up again, with new DNS verification values to publish.";
+export declare const LEGACY_SERVICE_MODE_MESSAGE = "Custom domains are available only for public apps.";
+/** Whether a stored error is the service-mode teardown marker, in either wording. */
+export declare function isServiceModeProvisioningError(error: string | null | undefined): boolean;
+export declare const CUSTOM_DOMAINS_NOT_CONFIGURED_MESSAGE = "Custom domains are not fully configured on this platform.";
+export declare const CUSTOM_DOMAIN_ROUTE_CONFLICT_MESSAGE = "This domain is already claimed elsewhere on the platform. Contact support to release it.";
+export interface DomainStateDnsInstruction {
+    type: string;
+    host: string;
+    value: string;
+    optional?: boolean;
+}
+/** Whether CAA records let one of the platform's certificate authorities issue (#1999). */
+export interface DomainStateCaaCheck {
+    status: "none" | "allows" | "blocks";
+    recordName: string | null;
+    via?: string;
+    ownerUnknown?: true;
+    allowedIssuers: string[];
+    platformIssuers: string[];
+}
+export interface DomainStateDnsCheck {
+    provider: string | null;
+    /** The DNS host's stable id (src/shared/dns-providers.ts). Absent for an unknown host and from older servers. */
+    providerId?: string;
+    nameservers: string[];
+    /** The zone the records go in, as the check found it. Absent from older servers and when no name answered NS. */
+    zone?: string;
+    records: Array<{
+        type: string;
+        host: string;
+        expected: string;
+        current: string[];
+        matches: boolean;
+        doubledAt?: string;
+    }>;
+    caa?: DomainStateCaaCheck;
+}
+/** What the derivation reads: a domain as any of the domain endpoints returns it. */
+export interface DomainStateInput {
+    hostname: string;
+    routingStatus: string;
+    tlsStatus: string;
+    dnsInstructions: DomainStateDnsInstruction[];
+    provisioningError: string | null;
+    activatedAt?: string | null;
+    dnsCheck?: DomainStateDnsCheck;
+    providerMessage?: string | null;
+    providerMessageAt?: string | null;
+    providerMessageSource?: string | null;
+}
+export type DomainState = "live" | "waiting_for_dns" | "dns_unverified" | "issuing_certificate" | "failed" | "expired";
+export type DomainRecordCheck = "found" | "missing" | "different" | "doubled" | "not_checked" | "apex_addresses";
+export interface DomainRecordStatus {
+    type: string;
+    name: string;
+    fqdn: string;
+    expected: string;
+    current: string[] | null;
+    ok: boolean | null;
+    check: DomainRecordCheck;
+    doubledAt?: string;
+    apex: boolean;
+    optional: boolean;
+}
+export declare function domainRecordStatuses(domain: DomainStateInput): DomainRecordStatus[];
+/**
+ * The `www.<domain>` to connect instead, when this hostname is a bare domain whose DNS host
+ * cannot point a root at a hostname at all (#1996): GoDaddy, Route 53, IONOS, Wix. Read only
+ * from a host the check both named and identified, so an unknown host, an older server and a
+ * domain with no check keep the ordinary records. Routing that is already active is the
+ * platform's own evidence that the root record exists, and wins over the profile.
+ */
+export declare function rootUnsupportedWwwHostname(domain: DomainStateInput): string | null;
+/**
+ * Whether a domain's instructions show "connect www instead" in place of the root record. It
+ * reads the status's own next step, so the display and the status cannot disagree: routing
+ * that is already active, an unknown host or an older server never show it, and a server's
+ * verdict is honoured even for a host this copy's table does not know.
+ */
+export declare function showsUseWww(next: {
+    action?: string;
+} | null | undefined): boolean;
+export declare function deriveDomainState(domain: DomainStateInput, records?: DomainRecordStatus[]): DomainState;
+export type DomainReasonCode = "records_missing" | "record_points_elsewhere" | "dns_changed_after_live" | "dns_not_checked" | "apex_unverifiable" | "dns_host_cannot_point_root" | "caa_blocks" | "certificate_pending" | "certificate_failed" | "hostname_failed" | "service_mode" | "claimed_elsewhere" | "platform_not_configured" | "provider_error" | "expired";
+export interface DomainReason {
+    code: DomainReasonCode;
+    /**
+     * The provider's own text, verbatim, when one was reported. `source` says whose it is: only
+     * "certificate_authority" may be presented as the certificate authority's; "hostname" is the
+     * hostname's own verification note and is worded neutrally.
+     */
+    providerMessage?: {
+        text: string;
+        seenAt: string;
+        source: "certificate_authority" | "hostname";
+    };
+}
+export type DomainNextAction = "none" | "add_records" | "replace_record" | "confirm_records" | "use_www" | "allow_ca_in_your_zone" | "ask_caa_controller" | "check_caa" | "wait" | "start_over" | "change_access_mode" | "add_again" | "recheck" | "contact_support";
+export interface DomainNextRecord {
+    type: string;
+    host: string;
+    value: string;
+    /**
+     * What to do with this one record. A step can mix them: a routing record pointing elsewhere is
+     * "replace" while a missing TXT value beside it is "add", because a name may hold several TXT
+     * values and replacing one could remove a value that must stay. TXT is never "replace".
+     */
+    action: "add" | "replace" | "confirm";
+    check: DomainRecordCheck;
+}
+export interface DomainNext {
+    /** Who has to act; absent when nobody does (a live domain). */
+    who?: "owner" | "platform";
+    action: DomainNextAction;
+    /** add/replace name only rows checked missing or different; not_checked rows only ever get confirm_records. */
+    records?: DomainNextRecord[];
+    /** CAA only: the name whose records decide, and the name of the owner's that points at it. */
+    caa?: {
+        recordName: string;
+        via?: string;
+        ownerUnknown?: true;
+        platformIssuers: string[];
+    };
+    /** The platform's next background re-read. It reads the status again and restarts nothing. */
+    nextCheckAt?: string;
+    /** use_www only: the hostname to add to the app instead. */
+    hostname?: string;
+}
+export interface DomainStatus {
+    state: DomainState;
+    /** Null only for a live domain. */
+    reason: DomainReason | null;
+    next: DomainNext;
+}
+/**
+ * The state, why, and the one next step. `state` is exactly deriveDomainState's; `reason` and
+ * `next` only refine it. Two rules hold throughout: a record nobody looked at is never called
+ * missing (it gets confirm_records, never add), and nothing here restarts validation or
+ * suggests that a restart speeds things up - Start over is named only for a failed certificate.
+ */
+export declare function deriveDomainStatus(domain: DomainStateInput, options?: {
+    nextCheckAt?: string | null;
+}): DomainStatus;

package/dist/domain-state.js

@@ -0,0 +1,248 @@
+// AUTO-GENERATED by scripts/generate-cli-package.mjs from the in-repo CLI source -- do not edit.
+// Edit src/cli or src/shared instead; this is regenerated on typecheck/test/build/pack.
+// One plain-language status for a custom domain (#1994): which of six states it is in, why,
+// and the one thing that happens next. The control plane computes it after its DNS check and
+// sends it on every domain; the CLI and the dashboard derive it from this same file when they
+// meet a server that predates the field, so the two paths cannot disagree. Copied into the CLI
+// tarball by scripts/generate-cli-package.mjs, so it imports nothing but dns-host and
+// dns-providers, which are copied beside it.
+import { relativeRecordName, zoneApexFor } from "./dns-host.js";
+import { dnsProviderProfile } from "./dns-providers.js";
+// The markers the control plane writes into provisioningError. Matched as exact strings, so a
+// wording change here changes what every reader recognises at once; the server's reconcilers
+// import them from this file for the same reason.
+// #751: the expired marker. Deliberately static - no configured day-count inside it - because
+// the reconcilers, claim checks and quota carve-outs key on this exact string.
+export const CUSTOM_DOMAIN_EXPIRED_MESSAGE = "This domain was removed because its DNS verification was never completed. Add the domain again to retry.";
+/** The name the CLI has always exported the expired marker under. */
+export const CUSTOM_DOMAIN_EXPIRED_TEXT = CUSTOM_DOMAIN_EXPIRED_MESSAGE;
+// Written onto a domain row when its app is in private_service mode, the only mode whose
+// domains are torn down (#750 kept them for otp/idp).
+export const CUSTOM_DOMAINS_SERVICE_MODE_MESSAGE = "Custom domains are not available for service-token apps, so this domain's hostname was removed. Switching the app to another access mode sets it up again, with new DNS verification values to publish.";
+// The wording rows torn down by earlier releases still carry. It says custom domains are
+// public-only, which is false (otp/idp apps keep theirs), so it is recognised and replaced.
+export const LEGACY_SERVICE_MODE_MESSAGE = "Custom domains are available only for public apps.";
+/** Whether a stored error is the service-mode teardown marker, in either wording. */
+export function isServiceModeProvisioningError(error) {
+    return error === CUSTOM_DOMAINS_SERVICE_MODE_MESSAGE || error === LEGACY_SERVICE_MODE_MESSAGE;
+}
+// Written when the platform has no fallback script, so nothing can create, re-adopt or tear
+// down this domain's route.
+export const CUSTOM_DOMAINS_NOT_CONFIGURED_MESSAGE = "Custom domains are not fully configured on this platform.";
+// Written when another script's route already holds the hostname.
+export const CUSTOM_DOMAIN_ROUTE_CONFLICT_MESSAGE = "This domain is already claimed elsewhere on the platform. Contact support to release it.";
+function normalizeDnsName(value) {
+    return value.trim().toLowerCase().replace(/\.$/, "");
+}
+// The value the server's DNS check compares against: TXT verbatim, names lowercased without a root dot.
+function checkedRecordValue(type, value) {
+    return type === "TXT" ? value : normalizeDnsName(value);
+}
+export function domainRecordStatuses(domain) {
+    const apex = zoneApexFor(domain.hostname, domain.dnsCheck?.zone);
+    return domain.dnsInstructions.map((instruction) => {
+        const type = instruction.type.toUpperCase();
+        const fqdn = normalizeDnsName(instruction.host);
+        const expected = checkedRecordValue(type, instruction.value);
+        // Matched on the expected value as well as host and type: the two TXT values of one name
+        // are separate rows, and keying on host and type alone gives both rows one verdict (#1986).
+        const seen = domain.dnsCheck?.records.find((entry) => entry.type.toUpperCase() === type && normalizeDnsName(entry.host) === fqdn && entry.expected === expected);
+        const atApex = type === "CNAME" && fqdn === apex;
+        const check = domainRecordCheck(seen, atApex);
+        return {
+            type,
+            name: relativeRecordName(fqdn, apex),
+            fqdn,
+            expected: instruction.value,
+            current: seen ? seen.current : null,
+            ok: check === "found" ? true : check === "missing" || check === "different" || check === "doubled" ? false : null,
+            check,
+            ...(check === "doubled" && seen?.doubledAt ? { doubledAt: seen.doubledAt } : {}),
+            apex: atApex,
+            optional: instruction.optional === true,
+        };
+    });
+}
+const IP_ADDRESS = /^(\d{1,3}(\.\d{1,3}){3}|[0-9a-f:]*:[0-9a-f:.]+)$/i;
+// The server looks a CNAME up and, finding none, falls back to the name's A records. At the
+// zone root that is exactly what a correct ALIAS/ANAME or flattened CNAME answers: addresses,
+// never the target name. So addresses at the apex are not evidence of a wrong record; they
+// cannot be compared from outside at all.
+function domainRecordCheck(seen, atApex) {
+    if (!seen)
+        return "not_checked";
+    if (seen.matches)
+        return "found";
+    if (seen.doubledAt)
+        return "doubled";
+    if (seen.current.length === 0)
+        return "missing";
+    if (atApex && seen.current.every((value) => IP_ADDRESS.test(value.trim())))
+        return "apex_addresses";
+    return "different";
+}
+// Unproven is decided by `ok`, not by listing check values: a check this code does not know yet
+// carries ok null and so reads as unknown, never as found. The one exception is an apex
+// answering with addresses, which the platform's own active routing vouches for.
+function isUnproven(record, routingActive) {
+    if (record.ok !== null)
+        return false;
+    return !(record.check === "apex_addresses" && routingActive);
+}
+/**
+ * The `www.<domain>` to connect instead, when this hostname is a bare domain whose DNS host
+ * cannot point a root at a hostname at all (#1996): GoDaddy, Route 53, IONOS, Wix. Read only
+ * from a host the check both named and identified, so an unknown host, an older server and a
+ * domain with no check keep the ordinary records. Routing that is already active is the
+ * platform's own evidence that the root record exists, and wins over the profile.
+ */
+export function rootUnsupportedWwwHostname(domain) {
+    const check = domain.dnsCheck;
+    if (!check?.provider || domain.routingStatus === "active")
+        return null;
+    if (dnsProviderProfile(check.providerId)?.apex.support !== "none")
+        return null;
+    const host = domain.hostname.toLowerCase().replace(/\.$/, "");
+    return host === zoneApexFor(host, check.zone) ? `www.${host}` : null;
+}
+/**
+ * Whether a domain's instructions show "connect www instead" in place of the root record. It
+ * reads the status's own next step, so the display and the status cannot disagree: routing
+ * that is already active, an unknown host or an older server never show it, and a server's
+ * verdict is honoured even for a host this copy's table does not know.
+ */
+export function showsUseWww(next) {
+    return next?.action === "use_www";
+}
+export function deriveDomainState(domain, records = domainRecordStatuses(domain)) {
+    if (domain.provisioningError === CUSTOM_DOMAIN_EXPIRED_MESSAGE)
+        return "expired";
+    if (domain.routingStatus === "failed" || domain.tlsStatus === "failed" || domain.provisioningError)
+        return "failed";
+    if (domain.routingStatus === "active" && domain.tlsStatus === "active")
+        return "live";
+    // No record the owner can publish will finish this domain: it waits on the owner choosing www.
+    if (rootUnsupportedWwwHostname(domain))
+        return "waiting_for_dns";
+    const required = records.filter((record) => !record.optional);
+    if (required.some((record) => record.ok === false))
+        return "waiting_for_dns";
+    const routingActive = domain.routingStatus === "active";
+    // An apex answering with addresses defers to the platform's own routing check: active means
+    // it found the record, pending means it has not yet.
+    const unproven = required.some((record) => isUnproven(record, routingActive));
+    if (unproven || (!domain.dnsCheck && required.length === 0)) {
+        // Routing still pending is the platform's own evidence that it has not seen the records.
+        return routingActive ? "dns_unverified" : "waiting_for_dns";
+    }
+    return "issuing_certificate";
+}
+function nextRecord(record) {
+    const action = record.ok === false ? (record.check === "different" && record.type !== "TXT" ? "replace" : "add") : "confirm";
+    return { type: record.type, host: record.fqdn, value: record.expected, action, check: record.check };
+}
+// Who controls the CAA record that decides, which decides the advice: in the owner's own zone
+// they can add an entry; at a CNAME target only whoever runs that name can; and when the
+// resolver did not say, nothing is handed over to edit at a name the owner may not control.
+function caaNext(caa) {
+    const summary = {
+        recordName: caa.recordName,
+        ...(caa.via ? { via: caa.via } : {}),
+        ...(caa.ownerUnknown ? { ownerUnknown: true } : {}),
+        platformIssuers: caa.platformIssuers,
+    };
+    if (caa.via)
+        return { who: "owner", action: "ask_caa_controller", caa: summary };
+    if (caa.ownerUnknown)
+        return { who: "owner", action: "check_caa", caa: summary };
+    const issuer = caa.platformIssuers[0];
+    return {
+        who: "owner",
+        action: "allow_ca_in_your_zone",
+        caa: summary,
+        ...(issuer ? { records: [{ type: "CAA", host: caa.recordName, value: `0 issue "${issuer}"`, action: "add", check: "missing" }] } : {}),
+    };
+}
+/**
+ * The state, why, and the one next step. `state` is exactly deriveDomainState's; `reason` and
+ * `next` only refine it. Two rules hold throughout: a record nobody looked at is never called
+ * missing (it gets confirm_records, never add), and nothing here restarts validation or
+ * suggests that a restart speeds things up - Start over is named only for a failed certificate.
+ */
+export function deriveDomainStatus(domain, options = {}) {
+    const records = domainRecordStatuses(domain);
+    const state = deriveDomainState(domain, records);
+    const source = domain.providerMessageSource === "certificate_authority" ? "certificate_authority" : "hostname";
+    // A hostname's own note while the owner is still publishing records is the expected "does not
+    // CNAME to this zone": it says nothing the records table does not, so it is not surfaced there.
+    const showMessage = Boolean(domain.providerMessage && domain.providerMessageAt) && state !== "live" && !(source === "hostname" && state === "waiting_for_dns");
+    const withMessage = (code) => showMessage ? { code, providerMessage: { text: domain.providerMessage, seenAt: domain.providerMessageAt, source } } : { code };
+    const nextCheckAt = options.nextCheckAt ? { nextCheckAt: options.nextCheckAt } : {};
+    const required = records.filter((record) => !record.optional);
+    if (state === "expired")
+        return { state, reason: withMessage("expired"), next: { who: "owner", action: "add_again" } };
+    if (state === "live")
+        return { state, reason: null, next: { action: "none" } };
+    if (state === "failed") {
+        const error = domain.provisioningError;
+        if (isServiceModeProvisioningError(error)) {
+            return { state, reason: withMessage("service_mode"), next: { who: "owner", action: "change_access_mode" } };
+        }
+        if (error === CUSTOM_DOMAINS_NOT_CONFIGURED_MESSAGE) {
+            return { state, reason: withMessage("platform_not_configured"), next: { who: "platform", action: "contact_support" } };
+        }
+        if (error === CUSTOM_DOMAIN_ROUTE_CONFLICT_MESSAGE) {
+            return { state, reason: withMessage("claimed_elsewhere"), next: { who: "platform", action: "contact_support" } };
+        }
+        if (!error && domain.tlsStatus === "failed") {
+            const fix = required.filter((record) => record.ok === false).map(nextRecord);
+            return {
+                state,
+                reason: withMessage("certificate_failed"),
+                next: { who: "owner", action: "start_over", ...(fix.length > 0 ? { records: fix } : {}) },
+            };
+        }
+        if (!error) {
+            // Routing failed with nothing recorded to say why. Nothing measured says the owner can
+            // fix it, so DNS edits are not prescribed: support is, and Re-check stays available.
+            return { state, reason: withMessage("hostname_failed"), next: { who: "platform", action: "contact_support" } };
+        }
+        // An upstream call threw; the background reconcile retries it, and Re-check retries now.
+        return { state, reason: withMessage("provider_error"), next: { who: "platform", action: "recheck" } };
+    }
+    const www = rootUnsupportedWwwHostname(domain);
+    if (www) {
+        return { state, reason: withMessage("dns_host_cannot_point_root"), next: { who: "owner", action: "use_www", hostname: www } };
+    }
+    if (state === "waiting_for_dns" || state === "dns_unverified") {
+        const wrong = required.filter((record) => record.ok === false);
+        if (wrong.length > 0) {
+            // TXT is never "replace": a name may hold several TXT values, so a missing one is added beside them.
+            const pointsElsewhere = wrong.some((record) => record.type !== "TXT" && record.check === "different");
+            const code = domain.activatedAt
+                ? "dns_changed_after_live"
+                : pointsElsewhere
+                    ? "record_points_elsewhere"
+                    : "records_missing";
+            return {
+                state,
+                reason: withMessage(code),
+                next: { who: "owner", action: pointsElsewhere ? "replace_record" : "add_records", records: wrong.map(nextRecord), ...nextCheckAt },
+            };
+        }
+        const routingActive = domain.routingStatus === "active";
+        const unproven = required.filter((record) => isUnproven(record, routingActive));
+        const code = unproven.length > 0 && unproven.every((record) => record.check === "apex_addresses") ? "apex_unverifiable" : "dns_not_checked";
+        return {
+            state,
+            reason: withMessage(code),
+            next: { who: "owner", action: "confirm_records", ...(unproven.length > 0 ? { records: unproven.map(nextRecord) } : {}), ...nextCheckAt },
+        };
+    }
+    // issuing_certificate: every required record was checked and found.
+    const caa = domain.dnsCheck?.caa;
+    if (caa?.status === "blocks" && caa.recordName) {
+        return { state, reason: withMessage("caa_blocks"), next: caaNext({ ...caa, recordName: caa.recordName }) };
+    }
+    return { state, reason: withMessage("certificate_pending"), next: { who: "platform", action: "wait", ...nextCheckAt } };
+}