Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Custom Domain Lifecycle & Fallback Origins

Managing custom domains across thousands of organizations presents unique challenges: DNS resolution, TLS termination, multi-tenant isolation, and automated certificate lifecycle management. This article explains how Shaf solves these problems using Cloudflare for SaaS custom hostnames.

The Host Routing Matrix

Shaf's edge middleware classifies every incoming HTTP request based on the Host header before any link resolution occurs:
Rendering diagram...
Each routing path is entirely isolated — a request to link.brand.com only resolves links created by the organization that owns that domain. Cross-tenant link resolution is impossible at the Worker level.

How Custom Domains Are Registered

Rendering diagram...

Cloudflare for SaaS & the Fallback Origin

Shaf maintains a dedicated fallback origin at cname.shaf.app. This single CNAME target handles routing for all tenant custom domains globally:
1. CNAME Mapping
When a customer creates a CNAME link.brand.com → cname.shaf.app, Cloudflare's Anycast network routes traffic for link.brand.com to Shaf's Worker infrastructure at the nearest PoP.
2. SNI & Certificate Dispatch
During the TLS handshake, Cloudflare inspects the Server Name Indication (SNI) extension to identify the requested hostname. It then serves an auto-provisioned SSL certificate signed specifically for link.brand.com — not the shaf.app wildcard cert.
3. Tenant Scoping
The Worker extracts the Host header value (link.brand.com) and queries D1/KV for the organization that owns it. Link lookups are strictly scoped to that tenant's dataset.
4. Cross-Tenant Isolation
If Tenant A created slug alpha on link.brand-a.com, Tenant B cannot resolve or overwrite it on link.brand-b.com. Isolation is enforced at the database schema level through composite primary keys on (domain, slug).

Certificate Lifecycle Management

Shaf uses Cloudflare for SaaS to automate the full certificate lifecycle. No manual renewal, no downtime risk:
PhaseWhat HappensDuration
Pending ValidationHostname registered; CNAME not yet confirmedUntil CNAME propagates
IssuanceCertificate issued & distributed to 300+ PoPs1–3 minutes after CNAME resolves
ActiveHTTPS live, edge TLS termination at nearest PoPOngoing
Auto-RenewalNew cert issued 30 days before expiryTransparent, zero downtime
Rendering diagram...
The entire resolution path — from incoming request to outgoing redirect — completes in 5–15ms at the edge.