@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/domain-provider-wildcard.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The wildcard driver — a container behind a proxy that already answers for
+ * `*.example.com`.
+ *
+ * This is the ordinary Docker shape and the reason the seam exists. An
+ * operator points one wildcard DNS record at their proxy, gets one wildcard
+ * certificate, and every workspace subdomain and every platform site subdomain
+ * resolves the moment it is created. There is no API to call because there is
+ * nothing to register: the name already works.
+ *
+ * So `attach` here is an assertion, not an action. That is exactly why the
+ * provider is never inferred — reporting a name as serving without checking is
+ * only honest when a human has said "my proxy answers for that whole apex",
+ * and `AGLYN_DOMAIN_PROVIDER=wildcard` is where they say it.
+ *
+ * ## What it will not claim
+ *
+ * A name OUTSIDE the configured suffixes — a customer's own `shop.acme.com` —
+ * is not covered by anyone's wildcard. This driver has no way to add it and no
+ * way to see it, so it says so: `skipped` on attach, `unknown` on status. It
+ * never reports such a name as serving on the strength of a suffix it does not
+ * match, and it never reports it as broken either, because an operator who
+ * added a vhost by hand has a working domain this cannot see. Operators who
+ * want custom domains registered automatically use the `webhook` driver, which
+ * can reach their proxy's own API.
+ */
+import { type DomainProvider } from './domain-provider';
+/**
+ * Whether `domain` is a name the operator's wildcard actually answers for.
+ *
+ * A wildcard record covers ONE label. `*.example.com` serves `a.example.com`
+ * and does not serve `a.b.example.com` — nor `example.com` itself — and a
+ * certificate issued for `*.example.com` covers exactly the same set. Matching
+ * on "ends with the suffix" would report both of those as serving, which for
+ * the deeper name is a TLS error the operator sees before we do.
+ */
+export declare function wildcardCovers(domain: string, suffixes: string[]): boolean;
+export declare function wildcardDomainProvider(): DomainProvider;

package/src/lib/server/domain-provider-wildcard.js

@@ -0,0 +1,163 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The wildcard driver — a container behind a proxy that already answers for
+ * `*.example.com`.
+ *
+ * This is the ordinary Docker shape and the reason the seam exists. An
+ * operator points one wildcard DNS record at their proxy, gets one wildcard
+ * certificate, and every workspace subdomain and every platform site subdomain
+ * resolves the moment it is created. There is no API to call because there is
+ * nothing to register: the name already works.
+ *
+ * So `attach` here is an assertion, not an action. That is exactly why the
+ * provider is never inferred — reporting a name as serving without checking is
+ * only honest when a human has said "my proxy answers for that whole apex",
+ * and `AGLYN_DOMAIN_PROVIDER=wildcard` is where they say it.
+ *
+ * ## What it will not claim
+ *
+ * A name OUTSIDE the configured suffixes — a customer's own `shop.acme.com` —
+ * is not covered by anyone's wildcard. This driver has no way to add it and no
+ * way to see it, so it says so: `skipped` on attach, `unknown` on status. It
+ * never reports such a name as serving on the strength of a suffix it does not
+ * match, and it never reports it as broken either, because an operator who
+ * added a vhost by hand has a working domain this cannot see. Operators who
+ * want custom domains registered automatically use the `webhook` driver, which
+ * can reach their proxy's own API.
+ */ import { domainStatus, normalizeHost } from "./domain-provider.js";
+/**
+ * The apexes the operator's DNS and certificate already cover.
+ *
+ * Falls back to the two the product itself hands out — the console's workspace
+ * domain and the tenant apex — because those are the names Aglyn generates and
+ * therefore the ones an operator choosing this driver is choosing it FOR. A
+ * deployment serving more than those, or serving them under different names
+ * per scope, lists them explicitly.
+ *
+ * ⛔ NO hardcoded apex behind those two. Elsewhere in the product an unset
+ * `NEXT_PUBLIC_TENANT_DOMAIN` may default to Aglyn's own name, because the
+ * consequence is a visibly wrong URL the operator corrects on their first
+ * click. Here the consequence is different in kind: this driver ASSERTS that
+ * the names it covers are being served, so a default would have an operator's
+ * install report `serving` for `*.aglyn.com` — a domain they do not own,
+ * cannot serve, and never named. An empty list covers nothing, which is the
+ * only honest answer when nobody has said what the proxy answers for.
+ */ function wildcardSuffixes() {
+    var _process_env_AGLYN_DOMAIN_WILDCARD_SUFFIXES, _process_env_NEXT_PUBLIC_WORKSPACE_DOMAIN, _process_env_NEXT_PUBLIC_TENANT_DOMAIN;
+    const configured = String((_process_env_AGLYN_DOMAIN_WILDCARD_SUFFIXES = process.env.AGLYN_DOMAIN_WILDCARD_SUFFIXES) != null ? _process_env_AGLYN_DOMAIN_WILDCARD_SUFFIXES : '').split(',').map((entry)=>normalizeHost(entry).replace(/^\*\./, '')).filter(Boolean);
+    if (configured.length) return configured;
+    return [
+        normalizeHost((_process_env_NEXT_PUBLIC_WORKSPACE_DOMAIN = process.env.NEXT_PUBLIC_WORKSPACE_DOMAIN) != null ? _process_env_NEXT_PUBLIC_WORKSPACE_DOMAIN : ''),
+        normalizeHost((_process_env_NEXT_PUBLIC_TENANT_DOMAIN = process.env.NEXT_PUBLIC_TENANT_DOMAIN) != null ? _process_env_NEXT_PUBLIC_TENANT_DOMAIN : '')
+    ].filter(Boolean);
+}
+/**
+ * Whether `domain` is a name the operator's wildcard actually answers for.
+ *
+ * A wildcard record covers ONE label. `*.example.com` serves `a.example.com`
+ * and does not serve `a.b.example.com` — nor `example.com` itself — and a
+ * certificate issued for `*.example.com` covers exactly the same set. Matching
+ * on "ends with the suffix" would report both of those as serving, which for
+ * the deeper name is a TLS error the operator sees before we do.
+ */ export function wildcardCovers(domain, suffixes) {
+    const host = normalizeHost(domain);
+    if (!host) return false;
+    return suffixes.some((suffix)=>{
+        if (!suffix || !host.endsWith(`.${suffix}`)) return false;
+        const label = host.slice(0, host.length - suffix.length - 1);
+        return label.length > 0 && !label.includes('.');
+    });
+}
+function uncoveredDetail(suffixes) {
+    return 'outside the wildcard' + (suffixes.length ? ` (${suffixes.join(', ')})` : '');
+}
+export function wildcardDomainProvider() {
+    const attach = async (_scope, name, options = {})=>{
+        const domain = normalizeHost(name);
+        const suffixes = wildcardSuffixes();
+        if (!domain) return {
+            outcome: 'skipped',
+            domain
+        };
+        if (!wildcardCovers(domain, suffixes)) {
+            return {
+                outcome: 'skipped',
+                domain,
+                detail: uncoveredDetail(suffixes)
+            };
+        }
+        /*
+     * A redirect request is satisfied here without an edge rule, because the
+     * app already serves one. The renamed workspace's old slug still resolves
+     * under the wildcard, and the canonical redirect in the app 308s it to the
+     * new one — which is the behaviour the edge rule was imitating. Reporting
+     * `attached` is therefore true rather than convenient.
+     */ void options.redirectTo;
+        return {
+            outcome: 'attached',
+            domain
+        };
+    };
+    return {
+        id: 'wildcard',
+        // Always, for the names it covers. There is no credential to be missing:
+        // the operator's assertion IS the configuration.
+        configured: ()=>true,
+        attach,
+        detach: async (_scope, name)=>{
+            const domain = normalizeHost(name);
+            const suffixes = wildcardSuffixes();
+            if (!domain) return {
+                outcome: 'skipped',
+                domain
+            };
+            /*
+       * Nothing to remove, and that is the honest answer rather than a
+       * comfortable one: a wildcard cannot un-serve one of its names, so a
+       * detached workspace subdomain keeps resolving until the app itself
+       * stops recognizing the slug. `not-found` says the entry this was asked
+       * to delete does not exist, which is exactly the case.
+       */ if (!wildcardCovers(domain, suffixes)) {
+                return {
+                    outcome: 'skipped',
+                    domain,
+                    detail: uncoveredDetail(suffixes)
+                };
+            }
+            return {
+                outcome: 'not-found',
+                domain
+            };
+        },
+        status: async (_scope, name)=>{
+            const domain = normalizeHost(name);
+            const suffixes = wildcardSuffixes();
+            if (!domain) return domainStatus(domain, 'skipped');
+            if (wildcardCovers(domain, suffixes)) {
+                return domainStatus(domain, 'serving');
+            }
+            // Not `not-attached`: this driver cannot see a custom domain either way,
+            // and `unknown` is the state that means "no evidence", which callers
+            // already treat as non-blocking.
+            return domainStatus(domain, 'unknown', {
+                detail: uncoveredDetail(suffixes)
+            });
+        }
+    };
+}
+
+//# sourceMappingURL=domain-provider-wildcard.js.map

package/src/lib/server/domain-provider-wildcard.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/domain-provider-wildcard.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The wildcard driver — a container behind a proxy that already answers for\n * `*.example.com`.\n *\n * This is the ordinary Docker shape and the reason the seam exists. An\n * operator points one wildcard DNS record at their proxy, gets one wildcard\n * certificate, and every workspace subdomain and every platform site subdomain\n * resolves the moment it is created. There is no API to call because there is\n * nothing to register: the name already works.\n *\n * So `attach` here is an assertion, not an action. That is exactly why the\n * provider is never inferred — reporting a name as serving without checking is\n * only honest when a human has said \"my proxy answers for that whole apex\",\n * and `AGLYN_DOMAIN_PROVIDER=wildcard` is where they say it.\n *\n * ## What it will not claim\n *\n * A name OUTSIDE the configured suffixes — a customer's own `shop.acme.com` —\n * is not covered by anyone's wildcard. This driver has no way to add it and no\n * way to see it, so it says so: `skipped` on attach, `unknown` on status. It\n * never reports such a name as serving on the strength of a suffix it does not\n * match, and it never reports it as broken either, because an operator who\n * added a vhost by hand has a working domain this cannot see. Operators who\n * want custom domains registered automatically use the `webhook` driver, which\n * can reach their proxy's own API.\n */\n\nimport {\n  domainStatus,\n  normalizeHost,\n  type DomainAttachOptions,\n  type DomainProvider,\n  type DomainResult,\n  type DomainScope,\n  type ProjectDomainStatus,\n} from './domain-provider'\n\n/**\n * The apexes the operator's DNS and certificate already cover.\n *\n * Falls back to the two the product itself hands out — the console's workspace\n * domain and the tenant apex — because those are the names Aglyn generates and\n * therefore the ones an operator choosing this driver is choosing it FOR. A\n * deployment serving more than those, or serving them under different names\n * per scope, lists them explicitly.\n *\n * ⛔ NO hardcoded apex behind those two. Elsewhere in the product an unset\n * `NEXT_PUBLIC_TENANT_DOMAIN` may default to Aglyn's own name, because the\n * consequence is a visibly wrong URL the operator corrects on their first\n * click. Here the consequence is different in kind: this driver ASSERTS that\n * the names it covers are being served, so a default would have an operator's\n * install report `serving` for `*.aglyn.com` — a domain they do not own,\n * cannot serve, and never named. An empty list covers nothing, which is the\n * only honest answer when nobody has said what the proxy answers for.\n */\nfunction wildcardSuffixes(): string[] {\n  const configured = String(process.env.AGLYN_DOMAIN_WILDCARD_SUFFIXES ?? '')\n    .split(',')\n    .map((entry) => normalizeHost(entry).replace(/^\\*\\./, ''))\n    .filter(Boolean)\n  if (configured.length) return configured\n  return [\n    normalizeHost(process.env.NEXT_PUBLIC_WORKSPACE_DOMAIN ?? ''),\n    normalizeHost(process.env.NEXT_PUBLIC_TENANT_DOMAIN ?? ''),\n  ].filter(Boolean)\n}\n\n/**\n * Whether `domain` is a name the operator's wildcard actually answers for.\n *\n * A wildcard record covers ONE label. `*.example.com` serves `a.example.com`\n * and does not serve `a.b.example.com` — nor `example.com` itself — and a\n * certificate issued for `*.example.com` covers exactly the same set. Matching\n * on \"ends with the suffix\" would report both of those as serving, which for\n * the deeper name is a TLS error the operator sees before we do.\n */\nexport function wildcardCovers(domain: string, suffixes: string[]): boolean {\n  const host = normalizeHost(domain)\n  if (!host) return false\n  return suffixes.some((suffix) => {\n    if (!suffix || !host.endsWith(`.${suffix}`)) return false\n    const label = host.slice(0, host.length - suffix.length - 1)\n    return label.length > 0 && !label.includes('.')\n  })\n}\n\nfunction uncoveredDetail(suffixes: string[]): string {\n  return (\n    'outside the wildcard' + (suffixes.length ? ` (${suffixes.join(', ')})` : '')\n  )\n}\n\nexport function wildcardDomainProvider(): DomainProvider {\n  const attach = async (\n    _scope: DomainScope,\n    name: string,\n    options: DomainAttachOptions = {},\n  ): Promise<DomainResult> => {\n    const domain = normalizeHost(name)\n    const suffixes = wildcardSuffixes()\n    if (!domain) return { outcome: 'skipped', domain }\n    if (!wildcardCovers(domain, suffixes)) {\n      return { outcome: 'skipped', domain, detail: uncoveredDetail(suffixes) }\n    }\n    /*\n     * A redirect request is satisfied here without an edge rule, because the\n     * app already serves one. The renamed workspace's old slug still resolves\n     * under the wildcard, and the canonical redirect in the app 308s it to the\n     * new one — which is the behaviour the edge rule was imitating. Reporting\n     * `attached` is therefore true rather than convenient.\n     */\n    void options.redirectTo\n    return { outcome: 'attached', domain }\n  }\n\n  return {\n    id: 'wildcard',\n    // Always, for the names it covers. There is no credential to be missing:\n    // the operator's assertion IS the configuration.\n    configured: () => true,\n    attach,\n    detach: async (_scope, name) => {\n      const domain = normalizeHost(name)\n      const suffixes = wildcardSuffixes()\n      if (!domain) return { outcome: 'skipped', domain }\n      /*\n       * Nothing to remove, and that is the honest answer rather than a\n       * comfortable one: a wildcard cannot un-serve one of its names, so a\n       * detached workspace subdomain keeps resolving until the app itself\n       * stops recognizing the slug. `not-found` says the entry this was asked\n       * to delete does not exist, which is exactly the case.\n       */\n      if (!wildcardCovers(domain, suffixes)) {\n        return { outcome: 'skipped', domain, detail: uncoveredDetail(suffixes) }\n      }\n      return { outcome: 'not-found', domain }\n    },\n    status: async (_scope, name): Promise<ProjectDomainStatus> => {\n      const domain = normalizeHost(name)\n      const suffixes = wildcardSuffixes()\n      if (!domain) return domainStatus(domain, 'skipped')\n      if (wildcardCovers(domain, suffixes)) {\n        return domainStatus(domain, 'serving')\n      }\n      // Not `not-attached`: this driver cannot see a custom domain either way,\n      // and `unknown` is the state that means \"no evidence\", which callers\n      // already treat as non-blocking.\n      return domainStatus(domain, 'unknown', { detail: uncoveredDetail(suffixes) })\n    },\n  }\n}\n"],"names":["domainStatus","normalizeHost","wildcardSuffixes","process","configured","String","env","AGLYN_DOMAIN_WILDCARD_SUFFIXES","split","map","entry","replace","filter","Boolean","length","NEXT_PUBLIC_WORKSPACE_DOMAIN","NEXT_PUBLIC_TENANT_DOMAIN","wildcardCovers","domain","suffixes","host","some","suffix","endsWith","label","slice","includes","uncoveredDetail","join","wildcardDomainProvider","attach","_scope","name","options","outcome","detail","redirectTo","id","detach","status"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GAED,SACEA,YAAY,EACZC,aAAa,QAMR,uBAAmB;AAE1B;;;;;;;;;;;;;;;;;CAiBC,GACD,SAASC;QACmBC,6CAMVA,2CACAA;IAPhB,MAAMC,aAAaC,QAAOF,8CAAAA,QAAQG,GAAG,CAACC,8BAA8B,YAA1CJ,8CAA8C,IACrEK,KAAK,CAAC,KACNC,GAAG,CAAC,CAACC,QAAUT,cAAcS,OAAOC,OAAO,CAAC,SAAS,KACrDC,MAAM,CAACC;IACV,IAAIT,WAAWU,MAAM,EAAE,OAAOV;IAC9B,OAAO;QACLH,eAAcE,4CAAAA,QAAQG,GAAG,CAACS,4BAA4B,YAAxCZ,4CAA4C;QAC1DF,eAAcE,yCAAAA,QAAQG,GAAG,CAACU,yBAAyB,YAArCb,yCAAyC;KACxD,CAACS,MAAM,CAACC;AACX;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASI,eAAeC,MAAc,EAAEC,QAAkB;IAC/D,MAAMC,OAAOnB,cAAciB;IAC3B,IAAI,CAACE,MAAM,OAAO;IAClB,OAAOD,SAASE,IAAI,CAAC,CAACC;QACpB,IAAI,CAACA,UAAU,CAACF,KAAKG,QAAQ,CAAC,CAAC,CAAC,EAAED,QAAQ,GAAG,OAAO;QACpD,MAAME,QAAQJ,KAAKK,KAAK,CAAC,GAAGL,KAAKN,MAAM,GAAGQ,OAAOR,MAAM,GAAG;QAC1D,OAAOU,MAAMV,MAAM,GAAG,KAAK,CAACU,MAAME,QAAQ,CAAC;IAC7C;AACF;AAEA,SAASC,gBAAgBR,QAAkB;IACzC,OACE,yBAA0BA,CAAAA,SAASL,MAAM,GAAG,CAAC,EAAE,EAAEK,SAASS,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAC;AAE/E;AAEA,OAAO,SAASC;IACd,MAAMC,SAAS,OACbC,QACAC,MACAC,UAA+B,CAAC,CAAC;QAEjC,MAAMf,SAASjB,cAAc+B;QAC7B,MAAMb,WAAWjB;QACjB,IAAI,CAACgB,QAAQ,OAAO;YAAEgB,SAAS;YAAWhB;QAAO;QACjD,IAAI,CAACD,eAAeC,QAAQC,WAAW;YACrC,OAAO;gBAAEe,SAAS;gBAAWhB;gBAAQiB,QAAQR,gBAAgBR;YAAU;QACzE;QACA;;;;;;KAMC,GACD,KAAKc,QAAQG,UAAU;QACvB,OAAO;YAAEF,SAAS;YAAYhB;QAAO;IACvC;IAEA,OAAO;QACLmB,IAAI;QACJ,yEAAyE;QACzE,iDAAiD;QACjDjC,YAAY,IAAM;QAClB0B;QACAQ,QAAQ,OAAOP,QAAQC;YACrB,MAAMd,SAASjB,cAAc+B;YAC7B,MAAMb,WAAWjB;YACjB,IAAI,CAACgB,QAAQ,OAAO;gBAAEgB,SAAS;gBAAWhB;YAAO;YACjD;;;;;;OAMC,GACD,IAAI,CAACD,eAAeC,QAAQC,WAAW;gBACrC,OAAO;oBAAEe,SAAS;oBAAWhB;oBAAQiB,QAAQR,gBAAgBR;gBAAU;YACzE;YACA,OAAO;gBAAEe,SAAS;gBAAahB;YAAO;QACxC;QACAqB,QAAQ,OAAOR,QAAQC;YACrB,MAAMd,SAASjB,cAAc+B;YAC7B,MAAMb,WAAWjB;YACjB,IAAI,CAACgB,QAAQ,OAAOlB,aAAakB,QAAQ;YACzC,IAAID,eAAeC,QAAQC,WAAW;gBACpC,OAAOnB,aAAakB,QAAQ;YAC9B;YACA,yEAAyE;YACzE,qEAAqE;YACrE,iCAAiC;YACjC,OAAOlB,aAAakB,QAAQ,WAAW;gBAAEiB,QAAQR,gBAAgBR;YAAU;QAC7E;IACF;AACF"}

package/src/lib/server/domain-provider.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * How a hostname gets served — the one seam the hosting vendor lives behind.
+ *
+ * ## The lock-in this removes
+ *
+ * Attaching a name was `POST https://api.vercel.com/...`, written out five
+ * times across the console routes and this library. Every workspace subdomain
+ * and every customer's custom domain therefore required a Vercel project and a
+ * Vercel token, and a self-hosted install had no way to register a name at all
+ * — it got `skipped` and a console that advertised a URL nothing resolved.
+ * "Bring your own Firebase, run it on Docker" cannot be true while the way a
+ * site becomes reachable is one vendor's API.
+ *
+ * So the vendor is a driver now. The three operations a name needs are the
+ * whole contract, and an operator picks — or writes — the implementation:
+ *
+ * | provider   | for                                                       |
+ * |------------|-----------------------------------------------------------|
+ * | `vercel`   | Aglyn's own hosting, and anyone else on Vercel             |
+ * | `wildcard` | a container behind a proxy with `*.example.com` DNS        |
+ * | `webhook`  | anything else — Caddy, Traefik, cert-manager, a registrar  |
+ * | `none`     | names are somebody else's job entirely                     |
+ *
+ * ## Why a webhook is the extension point and not a module path
+ *
+ * The obvious "supply your own layer" is a file path the app imports at boot.
+ * It does not survive the product: both apps are bundled by Next, so a path
+ * resolved at runtime is not in the bundle, and an operator running the
+ * published image has no build step to add one to. A webhook needs no rebuild,
+ * works from the shipped image, and is the same shape whether the operator's
+ * DNS lives in Caddy's admin API, a Traefik provider, or a shell script behind
+ * `nc`. The cost is one HTTP hop on an operation that already makes one.
+ *
+ * ## The contract every driver owes
+ *
+ * 1. **Never throw.** A caller creates orgs and renders cards with these
+ *    results; an exception takes down an org creation over a DNS API. Return
+ *    `failed` — or `skipped`, which is not a failure.
+ * 2. **Idempotent.** `attach` on a name already attached is `already-exists`,
+ *    which is success. Reconcile passes and create paths both run.
+ * 3. **`skipped` means "not my job", not "it went wrong".** It is what an
+ *    unconfigured driver returns, and callers treat it as neither success nor
+ *    failure.
+ * 4. **`unknown` status is not evidence of a problem.** {@link domainStateServes}
+ *    returns true for it deliberately: a probe that could not answer must not
+ *    strand every domain on a deployment whose provider has no status API.
+ */
+/**
+ * Which deployment a name should reach.
+ *
+ * Two, because Aglyn runs two apps: the console at `app.<domain>` with its
+ * per-workspace subdomains, and the tenant runtime that serves published
+ * sites and every customer's own domain. On Vercel they are separate projects;
+ * behind a proxy they are separate upstreams; for a webhook they are a field.
+ */
+export type DomainScope = 'console' | 'tenant';
+export type DomainOutcome = 'attached' | 'detached' | 'already-exists' | 'not-found' | 'skipped' | 'failed';
+export interface DomainResult {
+    outcome: DomainOutcome;
+    domain: string;
+    /** Why, when the outcome alone does not say it. Never user-facing prose. */
+    detail?: string;
+}
+export interface DomainAttachOptions {
+    /**
+     * Register the name as a REDIRECT to this bare hostname rather than serving
+     * the app on it — how a renamed workspace keeps its old slug working.
+     *
+     * A driver that cannot express a redirect returns `skipped` rather than
+     * attaching a serving name, because the two are not interchangeable: a
+     * serving twin is a second live copy of the console on a name that was
+     * supposed to forward.
+     */
+    redirectTo?: string;
+}
+export type ProjectDomainState = 'serving' | 'certificate-pending' | 'ownership-pending' | 'dns-misconfigured' | 'not-attached' | 'skipped' | 'unknown';
+/** One challenge record a provider wants before it will serve the name. */
+export interface ProjectDomainVerification {
+    type: string;
+    domain: string;
+    value: string;
+    reason?: string;
+}
+export interface ProjectDomainStatus {
+    state: ProjectDomainState;
+    domain: string;
+    /** Present when `state` is `ownership-pending`; what to add at the registrar. */
+    verification: ProjectDomainVerification[];
+    /**
+     * Records answering for this name that are not ours, as the provider sees
+     * them. A non-empty list on an otherwise-serving domain is the shadowing
+     * case: it resolves correctly some of the time.
+     */
+    conflicts: {
+        type?: string;
+        name?: string;
+        value?: string;
+    }[];
+    /** Why, when the state alone does not say it. */
+    detail?: string;
+}
+export interface DomainProvider {
+    /** Stable id, used in this module's log lines. Never a display name. */
+    readonly id: string;
+    /** Whether this deployment can actually register names for `scope`. */
+    configured(scope: DomainScope): boolean;
+    attach(scope: DomainScope, domain: string, options?: DomainAttachOptions): Promise<DomainResult>;
+    detach(scope: DomainScope, domain: string): Promise<DomainResult>;
+    status(scope: DomainScope, domain: string): Promise<ProjectDomainStatus>;
+}
+/**
+ * Whether a probed state means visitors may be sent to the domain (AGL-2011).
+ *
+ * The ONE definition of "serving", because it has to be. The predicate lived
+ * inline in `/api/domains/attach` and again in
+ * `/api/admin/finish-domain-attachments`, and the sweeper's own comment says
+ * why that is dangerous: a sweeper using a looser definition than the door it
+ * completes for re-introduces the bug that door was fixed to avoid.
+ *
+ * `certificate-pending` is NOT serving (AGL-1996): the name is accepted and
+ * routed but no certificate exists yet, so the destination answers with a TLS
+ * error. `unknown` and `skipped` ARE, deliberately — a status probe that could
+ * not answer is not evidence of a problem, and treating it as one would strand
+ * every domain on a deployment whose provider has no status API to ask.
+ */
+export declare function domainStateServes(state: ProjectDomainState): boolean;
+export declare function domainStatus(domain: string, state: ProjectDomainState, extra?: Partial<ProjectDomainStatus>): ProjectDomainStatus;
+export declare function normalizeHost(input: string): string;
+/**
+ * A redirect target reduced to a BARE HOSTNAME, or `null` if it is not one.
+ *
+ * Vercel rejects `https://aglyn.com` here with `bad_request`, whose message
+ * reads "Unable to redirect to https://…, because that domain is not added to
+ * the project" — it blames the target for being absent when the format was
+ * wrong. That misreading is why AGL-1273's redirect shipped looking correct
+ * and never once succeeded, and survived weeks before AGL-1365 caught it.
+ *
+ * Enforced at the seam rather than trusted per driver, so a webhook operator
+ * receives the same shape Vercel demands and no driver has to re-derive it.
+ */
+export declare function redirectHostname(target: string): string | null;
+/**
+ * Ceiling on any provider call (AGL-1136).
+ *
+ * These are awaited — org creation and rename wait for them — so an
+ * unresponsive DNS API would otherwise hang the operation until the platform
+ * killed the function, turning "the subdomain is not attached yet" into "the
+ * workspace could not be created". The whole point of the call being
+ * best-effort is that it can lose without taking anything with it, and a
+ * promise with no timeout cannot lose.
+ */
+export declare const DOMAIN_PROVIDER_TIMEOUT_MS = 5000;
+/** `AbortSignal.timeout`, without assuming the runtime has it. */
+export declare function domainDeadline(): AbortSignal | undefined;
+/** Whether a rejection was our own deadline rather than the network's. */
+export declare function abortedDetail(error: unknown): 'timeout' | 'network';
+/**
+ * The driver that registers nothing.
+ *
+ * Not an error state. A deployment can legitimately have names handled
+ * entirely outside the product — a platform team's own DNS pipeline, or an
+ * install that only ever uses path routing — and the correct behaviour there
+ * is silence, not a failure logged on every signup forever.
+ */
+export declare const NO_DOMAIN_PROVIDER: DomainProvider;
+export type DomainProviderId = 'vercel' | 'wildcard' | 'webhook' | 'none';
+/**
+ * The provider this deployment uses.
+ *
+ * ⚠️ Detection, when `AGLYN_DOMAIN_PROVIDER` is unset, deliberately only ever
+ * selects `vercel` — never `wildcard`. Wildcard reports a name as SERVING
+ * without checking anything, and inferring it from an apex an operator merely
+ * configured would have the console advertise addresses that resolve nowhere
+ * while showing a green chip. Claiming to serve a name is the operator's
+ * assertion to make, so it takes their explicit setting.
+ *
+ * Memoized on the environment values it reads rather than once per process, so
+ * a spec can change them between cases without a reset hook that production
+ * would carry for nobody.
+ */
+export declare function domainProvider(): DomainProvider;

package/src/lib/server/domain-provider.js

@@ -0,0 +1,221 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * How a hostname gets served — the one seam the hosting vendor lives behind.
+ *
+ * ## The lock-in this removes
+ *
+ * Attaching a name was `POST https://api.vercel.com/...`, written out five
+ * times across the console routes and this library. Every workspace subdomain
+ * and every customer's custom domain therefore required a Vercel project and a
+ * Vercel token, and a self-hosted install had no way to register a name at all
+ * — it got `skipped` and a console that advertised a URL nothing resolved.
+ * "Bring your own Firebase, run it on Docker" cannot be true while the way a
+ * site becomes reachable is one vendor's API.
+ *
+ * So the vendor is a driver now. The three operations a name needs are the
+ * whole contract, and an operator picks — or writes — the implementation:
+ *
+ * | provider   | for                                                       |
+ * |------------|-----------------------------------------------------------|
+ * | `vercel`   | Aglyn's own hosting, and anyone else on Vercel             |
+ * | `wildcard` | a container behind a proxy with `*.example.com` DNS        |
+ * | `webhook`  | anything else — Caddy, Traefik, cert-manager, a registrar  |
+ * | `none`     | names are somebody else's job entirely                     |
+ *
+ * ## Why a webhook is the extension point and not a module path
+ *
+ * The obvious "supply your own layer" is a file path the app imports at boot.
+ * It does not survive the product: both apps are bundled by Next, so a path
+ * resolved at runtime is not in the bundle, and an operator running the
+ * published image has no build step to add one to. A webhook needs no rebuild,
+ * works from the shipped image, and is the same shape whether the operator's
+ * DNS lives in Caddy's admin API, a Traefik provider, or a shell script behind
+ * `nc`. The cost is one HTTP hop on an operation that already makes one.
+ *
+ * ## The contract every driver owes
+ *
+ * 1. **Never throw.** A caller creates orgs and renders cards with these
+ *    results; an exception takes down an org creation over a DNS API. Return
+ *    `failed` — or `skipped`, which is not a failure.
+ * 2. **Idempotent.** `attach` on a name already attached is `already-exists`,
+ *    which is success. Reconcile passes and create paths both run.
+ * 3. **`skipped` means "not my job", not "it went wrong".** It is what an
+ *    unconfigured driver returns, and callers treat it as neither success nor
+ *    failure.
+ * 4. **`unknown` status is not evidence of a problem.** {@link domainStateServes}
+ *    returns true for it deliberately: a probe that could not answer must not
+ *    strand every domain on a deployment whose provider has no status API.
+ */ /**
+ * Which deployment a name should reach.
+ *
+ * Two, because Aglyn runs two apps: the console at `app.<domain>` with its
+ * per-workspace subdomains, and the tenant runtime that serves published
+ * sites and every customer's own domain. On Vercel they are separate projects;
+ * behind a proxy they are separate upstreams; for a webhook they are a field.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * Whether a probed state means visitors may be sent to the domain (AGL-2011).
+ *
+ * The ONE definition of "serving", because it has to be. The predicate lived
+ * inline in `/api/domains/attach` and again in
+ * `/api/admin/finish-domain-attachments`, and the sweeper's own comment says
+ * why that is dangerous: a sweeper using a looser definition than the door it
+ * completes for re-introduces the bug that door was fixed to avoid.
+ *
+ * `certificate-pending` is NOT serving (AGL-1996): the name is accepted and
+ * routed but no certificate exists yet, so the destination answers with a TLS
+ * error. `unknown` and `skipped` ARE, deliberately — a status probe that could
+ * not answer is not evidence of a problem, and treating it as one would strand
+ * every domain on a deployment whose provider has no status API to ask.
+ */ export function domainStateServes(state) {
+    return state !== 'not-attached' && state !== 'ownership-pending' && state !== 'dns-misconfigured' && state !== 'certificate-pending';
+}
+export function domainStatus(domain, state, extra = {}) {
+    return _extends({
+        state,
+        domain,
+        verification: [],
+        conflicts: []
+    }, extra);
+}
+const HOSTNAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/;
+export function normalizeHost(input) {
+    return String(input != null ? input : '').trim().toLowerCase().replace(/\.$/, '');
+}
+/**
+ * A redirect target reduced to a BARE HOSTNAME, or `null` if it is not one.
+ *
+ * Vercel rejects `https://aglyn.com` here with `bad_request`, whose message
+ * reads "Unable to redirect to https://…, because that domain is not added to
+ * the project" — it blames the target for being absent when the format was
+ * wrong. That misreading is why AGL-1273's redirect shipped looking correct
+ * and never once succeeded, and survived weeks before AGL-1365 caught it.
+ *
+ * Enforced at the seam rather than trusted per driver, so a webhook operator
+ * receives the same shape Vercel demands and no driver has to re-derive it.
+ */ export function redirectHostname(target) {
+    const raw = normalizeHost(target);
+    if (!raw) return null;
+    const host = raw.replace(/^[a-z][a-z0-9+.-]*:\/\//, '').split(/[/?#]/)[0].replace(/\.$/, '');
+    return HOSTNAME_PATTERN.test(host) ? host : null;
+}
+/**
+ * Ceiling on any provider call (AGL-1136).
+ *
+ * These are awaited — org creation and rename wait for them — so an
+ * unresponsive DNS API would otherwise hang the operation until the platform
+ * killed the function, turning "the subdomain is not attached yet" into "the
+ * workspace could not be created". The whole point of the call being
+ * best-effort is that it can lose without taking anything with it, and a
+ * promise with no timeout cannot lose.
+ */ export const DOMAIN_PROVIDER_TIMEOUT_MS = 5000;
+/** `AbortSignal.timeout`, without assuming the runtime has it. */ export function domainDeadline() {
+    try {
+        return AbortSignal.timeout(DOMAIN_PROVIDER_TIMEOUT_MS);
+    } catch (unused) {
+        return undefined;
+    }
+}
+/** Whether a rejection was our own deadline rather than the network's. */ export function abortedDetail(error) {
+    const name = error == null ? void 0 : error.name;
+    return name === 'TimeoutError' || name === 'AbortError' ? 'timeout' : 'network';
+}
+/**
+ * The driver that registers nothing.
+ *
+ * Not an error state. A deployment can legitimately have names handled
+ * entirely outside the product — a platform team's own DNS pipeline, or an
+ * install that only ever uses path routing — and the correct behaviour there
+ * is silence, not a failure logged on every signup forever.
+ */ export const NO_DOMAIN_PROVIDER = {
+    id: 'none',
+    configured: ()=>false,
+    attach: async (_scope, domain)=>({
+            outcome: 'skipped',
+            domain
+        }),
+    detach: async (_scope, domain)=>({
+            outcome: 'skipped',
+            domain
+        }),
+    status: async (_scope, domain)=>domainStatus(domain, 'skipped')
+};
+/**
+ * The configured provider id, or `null` to let {@link domainProvider} infer it.
+ *
+ * An explicit value always wins, including `none` — an operator switching a
+ * driver off while its credentials are still in the environment means it.
+ */ function requestedProviderId() {
+    var _process_env_AGLYN_DOMAIN_PROVIDER;
+    const raw = String((_process_env_AGLYN_DOMAIN_PROVIDER = process.env.AGLYN_DOMAIN_PROVIDER) != null ? _process_env_AGLYN_DOMAIN_PROVIDER : '').trim().toLowerCase();
+    if (!raw) return null;
+    if (raw === 'vercel' || raw === 'wildcard' || raw === 'webhook' || raw === 'none') {
+        return raw;
+    }
+    console.error(`[domain-provider] unknown AGLYN_DOMAIN_PROVIDER "${raw}" — falling back ` + 'to detection. Valid values: vercel, wildcard, webhook, none.');
+    return null;
+}
+let cached = null;
+/**
+ * The provider this deployment uses.
+ *
+ * ⚠️ Detection, when `AGLYN_DOMAIN_PROVIDER` is unset, deliberately only ever
+ * selects `vercel` — never `wildcard`. Wildcard reports a name as SERVING
+ * without checking anything, and inferring it from an apex an operator merely
+ * configured would have the console advertise addresses that resolve nowhere
+ * while showing a green chip. Claiming to serve a name is the operator's
+ * assertion to make, so it takes their explicit setting.
+ *
+ * Memoized on the environment values it reads rather than once per process, so
+ * a spec can change them between cases without a reset hook that production
+ * would carry for nobody.
+ */ export function domainProvider() {
+    var _process_env_AGLYN_DOMAIN_WEBHOOK_URL, _process_env_AGLYN_DOMAIN_WILDCARD_SUFFIXES, _process_env_NEXT_PUBLIC_WORKSPACE_DOMAIN, _process_env_NEXT_PUBLIC_TENANT_DOMAIN;
+    const requested = requestedProviderId();
+    const key = [
+        requested != null ? requested : '',
+        process.env.VERCEL_TOKEN ? '1' : '',
+        (_process_env_AGLYN_DOMAIN_WEBHOOK_URL = process.env.AGLYN_DOMAIN_WEBHOOK_URL) != null ? _process_env_AGLYN_DOMAIN_WEBHOOK_URL : '',
+        (_process_env_AGLYN_DOMAIN_WILDCARD_SUFFIXES = process.env.AGLYN_DOMAIN_WILDCARD_SUFFIXES) != null ? _process_env_AGLYN_DOMAIN_WILDCARD_SUFFIXES : '',
+        (_process_env_NEXT_PUBLIC_WORKSPACE_DOMAIN = process.env.NEXT_PUBLIC_WORKSPACE_DOMAIN) != null ? _process_env_NEXT_PUBLIC_WORKSPACE_DOMAIN : '',
+        (_process_env_NEXT_PUBLIC_TENANT_DOMAIN = process.env.NEXT_PUBLIC_TENANT_DOMAIN) != null ? _process_env_NEXT_PUBLIC_TENANT_DOMAIN : ''
+    ].join('\x00');
+    if ((cached == null ? void 0 : cached.key) === key) return cached.provider;
+    const provider = selectProvider(requested);
+    cached = {
+        key,
+        provider
+    };
+    return provider;
+}
+function selectProvider(requested) {
+    // Required lazily so a deployment pays for only the driver it uses, and so
+    // this module stays importable from an edge runtime that has no `fetch`
+    // credentials of its own.
+    switch(requested != null ? requested : process.env.VERCEL_TOKEN ? 'vercel' : 'none'){
+        case 'vercel':
+            return require('./domain-provider-vercel').VERCEL_DOMAIN_PROVIDER;
+        case 'wildcard':
+            return require('./domain-provider-wildcard').wildcardDomainProvider();
+        case 'webhook':
+            return require('./domain-provider-webhook').webhookDomainProvider();
+        default:
+            return NO_DOMAIN_PROVIDER;
+    }
+}
+
+//# sourceMappingURL=domain-provider.js.map