Document preview hosts and custom domain name rules on Fabric

fabric/cluster-creation-management.md

@@ -36,6 +36,28 @@ To edit an existing cluster:
    - Adding or removing additional regions.
 5. Click the "Save Changes" or "Confirm Payment Details" button to summarize and apply your modifications.
 
+## Preview Hosts
+
+Every cluster can serve short-lived copies of an application, such as one per pull request, under its own host name. A name one label below `app.` and the cluster's full host name reaches the [isolated application](/reference/v5/components/applications#isolated-applications) deployed with that name as its `host`:
+
+```
+pr-42.app.<cluster name>.<organization subdomain>.harperfabric.com
+```
+
+Fabric points every name under `app.<cluster name>.<organization subdomain>.harperfabric.com` at the cluster and adds `*.app.<cluster name>.<organization subdomain>.harperfabric.com` to each instance's certificate, so a new preview needs a deploy and nothing else: no custom domain to add, verify, or bind, and no setting to turn on.
+
+- Only isolated applications answer on preview hosts. A preview host that no running isolated application lists gets no response; it never reaches the cluster's other applications.
+- A preview host is exactly one label below `app.` and the cluster's host name: `pr-42.app.<cluster name>.…` works, and neither `a.pr-42.app.<cluster name>.…` nor `pr-42.<cluster name>.…` does.
+- Preview hosts are available on Colocated and Dedicated clusters.
+- New clusters serve preview hosts from the start. A cluster created earlier gains them one instance at a time, as each instance's certificate renews, which happens automatically within about seven weeks. Until every instance has renewed, a request for a preview host that reaches an instance without the new certificate fails with a certificate error, so on a cluster with several instances previews work only intermittently.
+
+### Previews share a site with production
+
+A preview runs under the cluster's own host name, so browsers treat it as the same site as your production application. Deploy as a preview only code you would trust in production.
+
+- A preview can set a cookie with `Domain=<cluster name>.<organization subdomain>.harperfabric.com`, which browsers then send to every application on the cluster, alongside any cookie of the same name the cluster set itself. For a cookie your production application relies on, such as a session cookie, use a name that starts with `__Host-` and set it with `Secure`, `Path=/` and no `Domain`, as browsers require of that prefix: a preview can then neither set nor replace it, and browsers never send it to a preview, as they do any cookie production sets with a `Domain`. Harper's own session cookie keeps its name, so it cannot take this protection.
+- `SameSite` does not separate a preview from production: a page served from a preview can send requests to your production application with production's cookies attached. Protect requests that change state with a CSRF token or an `Origin` check, not `SameSite` alone.
+
 ## Harper Deployment Types:
 
 ### Colocated:

fabric/custom-domains.md

@@ -38,6 +38,8 @@ Domain configuration is accessible through two primary paths:
 
 Harper Fabric will register the domain and display the DNS records you need to configure. A confirmation notification will appear: _“Domain added! Please add the TXT record above to your domain registrar.”_
 
+Domain names are not case-sensitive, and Fabric stores them in lowercase. A name must be a valid hostname, and cannot be a cluster's own host name or a name under it, which Fabric already uses for the cluster's instances and [preview hosts](/fabric/cluster-creation-management#preview-hosts). Once an organization has verified a domain, no other organization can register it.
+
 ## Configuring DNS Records
 
 After adding your domain, Fabric displays two DNS records in the **Next Steps** column of the domains table. You will need to add both of these records at your DNS registrar.