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.

Subpath Proxying Architecture & Security Model

Subpath Reverse Proxying allows organizations to brand and distribute short links under a subdirectory of their primary apex domain (e.g. acme.com/go/:slug) rather than dedicating a separate root domain (acme.link) or subdomain (go.acme.com).
While CNAME DNS delegation offloads the entire hostname to Shaf's Cloudflare for SaaS infrastructure, reverse proxying splits responsibility between your edge infrastructure and Shaf's edge runtime. This document explains the underlying engineering design, edge caching topology, and security boundaries.

1. The Edge TLS & SNI Challenge

In traditional CNAME delegation, Cloudflare for SaaS provisions an edge SSL certificate for the custom domain (e.g. link.acme.com), terminating TLS directly at Cloudflare's edge PoP.
When a customer proxies acme.com/go/* from their own infrastructure (such as an AWS ALB, Nginx droplet, or Cloudflare Worker), an architectural dilemma arises:
[Visitor] ---> (TLS: acme.com) ---> [Customer Proxy] ---> (TLS: ?) ---> [Shaf Cloudflare Edge]
  1. TLS Termination on Customer Origin: The customer terminates visitor HTTPS on their existing certificate for acme.com.
  2. Upstream TLS Handshake: When the customer's proxy initiates an outbound HTTPS connection to https://cname.shaf.app, it must send a Server Name Indication (SNI) in the TLS ClientHello.
  3. The Unrecognized Name Trap: If the proxy client sends acme.com as the SNI value, Cloudflare edge immediately rejects the handshake with SSL_ERROR_UNRECOGNIZED_NAME_ALERT because Shaf only holds SSL certificates for cname.shaf.app on that fallback origin.

The Resolution

To maintain end-to-end encryption without requiring custom certificates on Shaf's origin, the reverse proxy must:
  • Set SNI to cname.shaf.app (via proxy_ssl_name cname.shaf.app).
  • Set Host Header to cname.shaf.app.
  • Pass the customer's original hostname in the X-Forwarded-Host header (e.g. acme.com).
This allows Cloudflare edge to cleanly validate the TLS handshake for cname.shaf.app, while passing X-Forwarded-Host to Shaf's routing middleware.

2. Multi-Tenant Edge Routing & KV Caching

Shaf resolves short links at the edge using Cloudflare Workers and Cloudflare KV with zero database latency on active redirects.
Rendering diagram...

KV Cache Hygiene

Subpath domains are cached under two primary keys in Cloudflare KV:
  • domain:subpaths:${hostname}: Stores a JSON array of all active subpaths registered under that host, sorted by descending prefix length (longest prefix match first).
  • domain:lookup:${hostname}: Stores apex domain configuration when a full domain is also registered.
When a domain record is updated or deleted in the dashboard, Shaf atomically purges both keys across Cloudflare's global KV cache, preventing stale route collisions.

4-Tier Path Stripping Flexibility

Different reverse proxies forward URI paths differently. Shaf's routing engine handles all 4 proxy patterns transparently:
  1. Intact Path: Proxy forwards /go/promo -> Shaf extracts prefix /go and slug promo.
  2. Explicit Prefix Header: Proxy strips the path to /promo and sends X-Forwarded-Prefix: /go -> Shaf matches prefix /go and slug promo.
  3. Secret Token Association: Proxy strips the path to /promo with only X-Shaf-Proxy-Secret -> Shaf correlates the secret token to the domain's subpath record.
  4. Single Subpath Fallback: If a domain has exactly one registered subpath and forwards a stripped path with a valid secret, Shaf routes the link automatically.

3. Mutual Security Boundaries

Because subpath reverse proxying accepts traffic via X-Forwarded-* headers, Shaf implements a defense-in-depth security model to eliminate spoofing, denial-of-service, and server-side request forgery (SSRF).

A. Host-Spoofing Defense (X-Shaf-Proxy-Secret)

Without authentication, an attacker could send arbitrary requests to cname.shaf.app with X-Forwarded-Host: victim-company.com, stealing link quota or injecting unauthorized redirects.
Every subpath domain registered in Shaf generates a high-entropy secret token:
spt_live_4k8b1n9x2p7v5m0q
  • Every request routed through a subpath_proxy domain must include this token in X-Shaf-Proxy-Secret.
  • Requests missing the token or providing an incorrect token are immediately rejected with HTTP 401 Unauthorized.

B. Visitor IP & Analytics Integrity

Preserving accurate visitor analytics (geographic country, city, and device type) requires parsing the client's real IP address from X-Forwarded-For.
To prevent spoofing:
  • On public CNAME routes, Shaf ignores untrusted client-supplied X-Forwarded-For headers and uses Cloudflare's verified CF-Connecting-IP.
  • On subpath proxy routes, Shaf parses the leftmost IP in X-Forwarded-For only after successfully verifying X-Shaf-Proxy-Secret (event.context.isSubpathProxy === true).

C. SSRF-Hardened Automated Verification Probes

When an administrator verifies a subpath proxy in the dashboard, Shaf executes an automated health probe to:
https://${domain}${pathPrefix}/__shaf_probe
To prevent attackers from using Shaf as an SSRF proxy to scan internal networks or cloud metadata APIs, the probe engine enforces strict network constraints:
  • Loopback Blocking: Rejects localhost, 127.0.0.1, ::1, and *.localhost.
  • Private RFC 1918 Blocking: Rejects 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16.
  • Cloud Metadata Blocking: Explicitly blocks AWS/GCP/Azure metadata IP 169.254.169.254.
  • System Domain Loop Prevention: Rejects probes targeting Shaf core domains (shaf.app, dash.shaf.app, shaf.is, cname.shaf.app).
  • No-Redirect Policy: Probe requests use redirect: 'manual' with a strict 5-second timeout, preventing redirect-based SSRF pivoting.

4. Subpath Root Handling

When a visitor navigates directly to https://acme.com/go without a link slug, Shaf's router recognizes this as a subpath root request (isSubpathRoot = true).
Rather than returning a 404 error page, Shaf:
  1. Checks for a configured rootRedirectUrl on the domain record and redirects to that target (e.g. https://acme.com/deals).
  2. If no custom URL is configured, safely redirects the visitor to the tenant's primary website (https://acme.com), ensuring a seamless user experience.