# Complete DNS, Domain Routing & Cloudflare Deployment Guide for KeyExchange.Org

**Author:** Professor Ash (`ash@keyexchange.org`)  
**Domain:** `keyexchange.org` & `www.keyexchange.org`  
**Cloudflare Account:** `admin@stellartalons.com`  
**Current Registrar:** Squarespace Domains  
**Cloudflare Pages Project:** `keyexchange-portal` (Target: `keyexchange-portal.pages.dev`)  
**Version:** `1.2.0` (SemVer 2.0.0)  
**Date:** `2026-10-26T14:40:00Z`  

---

## 1. Critical Diagnostics: Root Cause Analysis

### A. Global Subdomain Collision on `keyexchange.pages.dev`
- **What happened:** When querying or attempting to claim `keyexchange.pages.dev`, DNS resolves to an unrelated third-party website (`cheapkey.trade`).
- **Technical Root Cause:** Cloudflare Pages subdomains (`*.pages.dev`) share a single, flat global namespace across all Cloudflare users worldwide. Project names are allocated strictly on a first-come, first-served basis. The generic name `keyexchange` was claimed by a third party before this deployment.
- **The Permanent Fix:** Our official Cloudflare Pages project has been renamed to **`keyexchange-portal`**, targeting **`keyexchange-portal.pages.dev`**. This subdomain is verified available and unclaimed, reserving the canonical namespace exclusively for KeyExchange.Org.

### B. Understanding Cloudflare Error 1003: Direct IP Access Not Allowed
- **What happened:** Navigating directly to raw Cloudflare Anycast IP addresses (e.g. `http://172.67.180.12/` or `http://104.21.48.20/`) in a web browser produces:
  ```
  error code: 1003 Direct IP Access Not Allowed
  ```
- **Technical Root Cause:** Cloudflare operates a multi-tenant reverse proxy Anycast network. Millions of domains share the exact same edge IP addresses. Cloudflare edge nodes rely entirely on the HTTP `Host:` header (and TLS Server Name Indication / SNI) to route incoming packets to the correct customer origin or Cloudflare Pages project. When an IP address is entered directly in a browser URL bar, the request arrives without a valid domain `Host:` header, and Cloudflare immediately terminates the connection with Error 1003.
- **Rule of Thumb:** **NEVER** configure static A records with raw Cloudflare Anycast IPs for Cloudflare Pages. Cloudflare Pages is a dynamic serverless edge deployment whose underlying IP addresses rotate dynamically and must always be referenced by hostname or managed through Cloudflare's proxied DNS.

---

## 2. Recommended Architecture: Method A vs Method B

```mermaid
flowchart TD
    subgraph MethodA ["Method A: Nameserver Delegation (Foolproof & Recommended)"]
        UserA["Seeker Browser (keyexchange.org / www)"] --> CF_DNS["Cloudflare Authoritative DNS"]
        CF_DNS --> AutoFlatten["Automatic CNAME Flattening (@ and www)"]
        AutoFlatten --> PagesA["Cloudflare Pages: keyexchange-portal.pages.dev"]
        PagesA --> EdgeA["Edge Worker & Microservice Origin"]
    end

    subgraph MethodB ["Method B: Squarespace Custom Records (Alternative)"]
        UserB["Seeker Browser"] --> SQ_DNS["Squarespace DNS"]
        SQ_DNS -- "www" --> CNAME_B["CNAME: keyexchange-portal.pages.dev"]
        SQ_DNS -- "@" --> Redirect_B["Squarespace 301 URL Forwarding to www"]
        CNAME_B --> PagesB["Cloudflare Pages: keyexchange-portal.pages.dev"]
        Redirect_B --> CNAME_B
    end
```

---

## 3. Method A: Cloudflare Nameserver Delegation (STRONGLY RECOMMENDED)

This method moves DNS management to Cloudflare while domain registration and renewal remain at Squarespace. It eliminates all manual IP configuration, enables automatic CNAME flattening at the apex (`@`), provides automatic universal TLS 1.3 certificates, and activates edge DDoS protection.

### Step 1: Add Domain to Cloudflare Dashboard
1. Log in to [Cloudflare Dashboard](https://dash.cloudflare.com) using your credentials:
   - **Email:** `admin@stellartalons.com`
   - **Password:** *(stored in `credentials/cloudflare.txt`)*
2. In the top-right corner, click **"Add a site"** (or **"Add Domain"**).
3. Enter `keyexchange.org` and click **Continue**.
4. Select the **Free** plan ($0/month) at the bottom and click **Continue**.
5. Cloudflare will scan for existing DNS records. Click **Continue**.
6. Cloudflare will present **Two Assigned Nameservers**. They will look similar to:
   - `algin.ns.cloudflare.com`
   - `tina.ns.cloudflare.com`
   *(Copy down the exact two nameservers shown on your screen).*

### Step 2: Set Custom Nameservers in Squarespace
1. Log in to [Squarespace Domains Console](https://account.squarespace.com/domains).
2. Click on **`keyexchange.org`**.
3. In the navigation panel, click **Nameservers** (located above "DNS Settings").
4. Select the radio button: **"Use custom nameservers"**.
5. Click **"Add Nameserver"** and enter:
   - Nameserver 1: *(Your first assigned Cloudflare nameserver, e.g. `algin.ns.cloudflare.com`)*
   - Nameserver 2: *(Your second assigned Cloudflare nameserver, e.g. `tina.ns.cloudflare.com`)*
6. Click **Save** (and confirm any registry lock prompt if requested).

### Step 3: Connect Custom Domain to Cloudflare Pages
1. In Cloudflare Dashboard, navigate to **Compute (Workers & Pages)** > **Pages**.
2. Select your project: **`keyexchange-portal`**.
3. Go to the **Custom domains** tab.
4. Click **Set up a custom domain**.
5. Enter: `keyexchange.org` and click **Continue**.
6. Cloudflare detects that nameservers are managed on Cloudflare and automatically provisions the proxied DNS record with a single click.
7. Repeat the same step for `www.keyexchange.org`.
8. Both apex and `www` are now securely routed with zero manual record configuration.

---

## 4. Method B: Squarespace Custom Records (Keeping Squarespace Nameservers)

If you must keep Squarespace as the authoritative DNS provider, use CNAME mapping for `www` and Squarespace URL Forwarding for the apex `@`.

> [!WARNING]
> Standard DNS RFC 1034 does not permit CNAME records on an apex domain (`@`). Do not attempt to add raw IP addresses for Cloudflare Pages, as direct IP requests fail with Error 1003.

### Step 1: Add CNAME Record for `www` in Squarespace
1. In [Squarespace Domains](https://account.squarespace.com/domains), click **`keyexchange.org`** > **DNS Settings**.
2. Under the **"Custom Records"** section, click **"Add record"**.
3. Fill in:
   - **Host:** `www`
   - **Type:** `CNAME`
   - **Data / Points to:** `keyexchange-portal.pages.dev`
   - **TTL:** `3600` (or `Automatic`)
4. Click **Save**.

### Step 2: Configure Apex Forwarding in Squarespace
1. In Squarespace domain settings for `keyexchange.org`, navigate to **Domain Forwarding** (or **URL Redirects**).
2. Click **"Add Rule"** (or **"Add Forward"**).
3. Set:
   - **Forward From:** `keyexchange.org`
   - **Forward To:** `https://www.keyexchange.org`
   - **Redirect Type:** `301 Permanent Redirect`
   - **Forward Path:** Checked / Enabled
   - **SSL Enabled:** Checked
4. Click **Save**.

### Step 3: Authorize Custom Domain in Cloudflare Pages
1. In Cloudflare Dashboard, go to **Workers & Pages** > **`keyexchange-portal`** > **Custom domains**.
2. Click **Set up a custom domain**.
3. Enter: `www.keyexchange.org`.
4. Cloudflare will verify the CNAME record in Squarespace and provision the SSL certificate.

---

## 5. Automated Deployment & Wrangler CLI Integration

Our project is pre-configured with Cloudflare Wrangler CLI integration in `deploy/cloudflare/wrangler.toml` and `package.json`.

### Wrangler Configuration (`deploy/cloudflare/wrangler.toml`)
```toml
name = "keyexchange-portal"
compatibility_date = "2026-10-26"
pages_build_output_dir = "dist"

[vars]
ENVIRONMENT = "production"
PORTAL_NAME = "KeyExchange.Org"
AUTHOR_EMAIL = "ash@keyexchange.org"
TAGLINE = "A knowledge exchange portal for Seekers, and Believers are welcome!"
```

### Automated Deploy Command
To deploy directly to Cloudflare Pages from the terminal:
```bash
# 1. Rebuild the production assets
npm run build

# 2. Deploy to Cloudflare Pages under project keyexchange-portal
npm run deploy:cf
```

### Headless Deployment with Cloudflare API Token
For non-interactive CI/CD or terminal deployments:
1. Generate an API Token at [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens) with template **"Edit Cloudflare Workers"**.
2. Run deployment using the token:
```bash
export CLOUDFLARE_API_TOKEN="your-cloudflare-api-token"
export CLOUDFLARE_ACCOUNT_ID="your-account-id"

npx wrangler pages deploy dist --project-name=keyexchange-portal
```

---

## 6. Live Verification & Propagation Checks

Once DNS has been updated, run the following verification checks from any terminal:

```bash
# 1. Verify Nameserver delegation (Method A)
dig +short NS keyexchange.org

# 2. Verify CNAME resolution for www (Method B or A)
dig +short CNAME www.keyexchange.org
# Expected: keyexchange-portal.pages.dev (or Cloudflare Anycast proxied IPs when active)

# 3. Verify Cloudflare Edge HTTPS Handshake
curl -I https://www.keyexchange.portal.pages.dev || true
curl -I https://keyexchange-portal.pages.dev

# 4. Verify www domain response and HTTP status
curl -s -o /dev/null -w "%{http_code}\n" https://www.keyexchange.org

# 5. Verify apex redirect (if using Method B)
curl -I https://keyexchange.org
# Expected: HTTP/2 301 Location: https://www.keyexchange.org
```

---

## 7. Summary of Changes in v1.2.0

| Parameter | Previous Value | New Corrected Value | Reason |
| :--- | :--- | :--- | :--- |
| **Pages Project Name** | `keyexchange` | `keyexchange-portal` | Prevents collision with third-party `cheapkey.trade` |
| **Pages Subdomain** | `keyexchange.pages.dev` | `keyexchange-portal.pages.dev` | Verified unclaimed and dedicated to KeyExchange.Org |
| **Apex Record Strategy** | Static A records (`172.67...`) | Cloudflare Nameserver Delegation (Method A) or 301 URL Forwarding (Method B) | Eliminates Cloudflare Edge Error 1003 Direct IP Access Not Allowed |
| **Wrangler Script** | `--project-name=keyexchange` | `--project-name=keyexchange-portal` | Synchronized with project configuration |