Custom Domains

A root domain (two labels, no leading www). Ownership is proven with a TXT record; routing points an A record at your ingress and, because apex A-records can't be reliably auto-probed, usually needs the explicit activate step after verification.

The conventional www host. Gated by allowWwwDomains. Verified by TXT and routed by CNAME to your cnameTarget.

Any other sub-host the tenant controls. Verified by TXT and routed by CNAME, so it can auto-activate once the CNAME resolves to the target.

A host under your own platformBaseDomain. Detected as first-party (not a customer domain) so it is never treated as an apex the tenant must verify.

Master switch. When false nothing registers — no routes, no tables, no tenant-resolution indexing.

Route prefix the domain endpoints mount under (e.g. /domains/hostnames, /domains/resolve).

How hostnames are verified and given TLS. manual_dns needs no third-party API; cloudflare_for_saas issues managed certificates. If cloudflare_for_saas is selected but the cloudflare block is incomplete, the framework logs a warning and falls back to manual DNS rather than crashing.

• manual_dns— No external API. Issues DNS instructions and verifies ownership against live DNS; TLS is assumed terminated by your ingress.
• cloudflare_for_saas— Creates Cloudflare custom hostnames and DV certificates, tracking activation and cert issuance as two independent lifecycles.

Your own base domain, e.g. "platform.com". Enables exact platform-subdomain detection and auto-reserves the apex so no tenant can claim it.

Env-name-or-literal. The CNAME/A target customer hostnames point at (your ingress). Manual DNS uses this to build routing instructions and to probe live CNAMEs for auto-activation. If left unset, the resolved target falls back to cloudflare.cnameTarget.

Example: "customers.platform.com"

Whether tenants may attach apex (root) domains. When false, an apex-kind hostname is rejected at create time.

Whether tenants may attach www hostnames. When false, a www-kind hostname is rejected at create time.

Enables the Domain Concierge flow — requesting brand-new domain registrations through the API. Off by default; registration requests throw when disabled.

Hostnames tenants may never claim (normalized on load). createHostname rejects any match, alongside the platformBaseDomain itself.

Example: ["www.platform.com", "api.platform.com"]

Ownership-challenge tuning.

Cloudflare for SaaS credentials. Each field is env-name-or-literal. The block resolves to null (and the provider falls back to manual DNS) unless accountId, zoneId and apiToken all resolve to non-empty values.

Managed-registration (Domain Concierge) settings.

Manual DNS always issues a TXT record. Name is <txtRecordPrefix>.<normalizedHostname>, value is a fixed nucleus-domain-verification=<48-hex-char token>. A live resolveTxt lookup that finds the token flips verification_status to verified.

For non-apex hostnames with a cnameTarget set, a live resolveCname probe checks the host points at your target. A match sets routing_status active; otherwise it stays pending until the record propagates.

Apex domains route via an A record, which cannot be auto-probed. After TXT verification succeeds, an admin activate call sets routing active — this is the expected extra step for apex hostnames on manual DNS.

Verification status can be pending, verified or failed; 'expired' is a defined status but the framework never auto-transitions to it. Each challenge row stores an expiry timestamp (derived from challengeTtlSeconds), yet nothing enforces it — loadPendingChallenge selects the still-pending challenge with no expiry filter, so re-running verify simply re-checks live DNS. A freshly created hostname starts at 'pending_verification' (its status before any verify call); it only moves to 'verifying' after a verify / refresh-status call whose result isn't yet ready and hasn't failed. Failed verification moves the hostname to failed; a not-yet-ready-but-not-failed hostname sits in verifying. Instructions are idempotent — getInstructions rebuilds the records from dns_target plus the hostname's challenge rows (queried by hostname id, regardless of status) any time you need to re-show the steps.

TLS is assumed terminated at your platform ingress, so certificate_status is not_required from the start. The framework only proves ownership and points routing at cnameTarget; you bring the wildcard/edge certificate.

Creates a Cloudflare custom hostname with an SSL DV certificate (min TLS 1.2) and tracks two independent lifecycles: hostname activation (result.status) and certificate issuance (result.ssl.status). Blocked/moved/deleted marks routing failed; a validation-timed-out, deactivating OR deleted SSL status marks the certificate failed, and ssl validation errors (validation_errors > 0) mark verification failed.

Cloudflare for SaaS uses its own ownership_verification and ssl.validation_records — not the _nucleus-challenge TXT — so the DNS records you surface to the tenant come from Cloudflare, not the manual TXT challenge.

At boot the registry indexes every domain_hostnames row where status is active and whose tenant_id maps to a known tenant. It is a safe no-op if the table is absent, and a hostname with no matching tenant is simply skipped.

The index stays live: activate / verify-success calls registerDomainHostname and disable calls unregisterDomainHostname, so newly-verified hostnames start resolving immediately and disabled ones stop.

Given a hostname (or the request host header) returns { hostnameId, tenantId, schemaName, isPrimary, redirectToHostname } for the active match — the primitive an edge/proxy uses to route a raw hostname to a tenant. 400 if no hostname, 404 if no active match.

Body { requestedDomain, ownerId, ownerType?, tenantId?, registrantOwnerType?, termsVersion (required), termsAccepted (required true), autoRenew? }. ownerType is one of 'tenant' | 'organization' | 'user' | 'external' and defaults to 'tenant' when omitted. termsAccepted must be truthy or the request throws.

New records start at awaiting_payment (not draft), stamped with the registrar provider and registrantOwnerType. This shows the common path; transition() accepts any RegistrationStatus, so records may move through availability_checked, registering, active, failed, transfer_requested, transferred_out, cancelled and expired.

Your deployment advances a registration by calling transition(id, status, patch?) with { registeredDomain, providerRegistrationId, priceAmount, currency, renewalDate, failureReason }. Each transition emits a registration_<status> event. cancel sets cancelled; requestTransferOut sets transfer_requested.

Full-hostname → tenant lookup. Falls back to the host header; 400 if none, 404 if no active match.

Create a hostname ({ hostname, ownerId, ownerType?, tenantId?, schemaName?, isPrimary? }) → { hostname, instructions }. ownerType is one of 'tenant' | 'organization' | 'user' | 'external' and defaults to 'tenant' when omitted. 400 on an invalid, reserved or duplicate hostname. Non-godmin callers have tenantId and schemaName forced to their own verified tenant.

List hostnames. Non-godmin callers are pinned to their own tenant (client tenantId/ownerId filters ignored); godmin may filter by tenantId, ownerId, or list all.

Fetch one. 404 if missing or cross-tenant (existence not confirmed for other tenants).

Rebuild the DNS records to apply (A/CNAME target plus challenge rows). Idempotent; 404 if cross-tenant.

Run ownership + provider status re-sync and recompute readiness. 404 if cross-tenant.

Admin force-activate. Requires verification_status='verified' (else 400); the expected step for apex hostnames on manual DNS. 404 if cross-tenant.

Delete the provider hostname, set status disabled and remove it from the resolution index. 404 if cross-tenant.

Mark this hostname primary, clearing the flag on others in the same tenant/owner scope. 404 if cross-tenant.

Alias of verify. 404 if cross-tenant.

Request a managed registration (Domain Concierge). Non-godmin tenantId is bound to the caller and registrantOwnerType forced to 'customer'.

List registrations. Non-godmin callers are pinned to their own tenant (filters ignored).

Fetch one registration. 404 if missing or cross-tenant.

Move the registration to status cancelled. 404 if cross-tenant.

Move the registration to status transfer_requested. 404 if cross-tenant.

On POST /domains/hostnames a non-godmin caller has BOTH tenantId and schemaName derived server-side from the request's verified x-tenant-schema (resolveTenantIdForSchema). A body schemaName naming a different tenant → 403 "Cannot bind a hostname to another tenant's schema"; a body tenantId naming a different tenant → 403 "Cannot bind a hostname to another tenant". Guarding schemaName alone was insufficient because tenantId is the actual routing key.

List ignores client tenantId/ownerId filters and pins to the caller's tenant. GET :id, instructions, and every lifecycle op (verify / activate / disable / make-primary / refresh-status) load and ownership-check the record before mutating, returning 404 "Hostname not found" on a cross-tenant id so existence is never confirmed.

POST /domains/registrations binds tenantId to the caller's verified tenant (foreign → 403 "Cannot register a domain for another tenant") and forces registrantOwnerType:'customer'. Requesting 'platform' (billing the platform as renewal payer) → 403 "Only a platform admin may register as 'platform'". List pins to the caller's tenant; GET :id, cancel and transfer-out return 404 cross-tenant.