# Caib tenant bridge: direct CNAME vs CDN-proxied (`orange cloud`)

**Audience:** domain / DNS administrators connecting `caib.<customer-apex>` to the Caib registry.

## What we are configuring

- **Host:** `caib.<apex>` (example: `caib.example.com`).
- **Goal:** browsers and API clients reach the **registry** that serves the tenant’s machine-readable catalogue.
- **TXT** at `_caib.<apex>` is separate: it binds **individual user accounts** to the client. This document is only about the **bridge hostname** (`caib.<apex>`).

## Option A — Direct CNAME (recommended for automation)

1. Create a **DNS-only** record (in Cloudflare: **grey cloud**, “DNS only”).
2. **Type:** `CNAME`
3. **Name:** `caib` (or `caib.<apex>` depending on the panel).
4. **Target:** the hostname Caib gives you (typically `registry.caib.io` — use the exact value shown in the Caib UI).

**Why Caib prefers this**

- Public resolvers see a normal **CNAME chain**; our checks show **Direct (green)**.
- **Bots, crawlers, and assistants** that rely on simple DNS (no special CDN behaviour) are more likely to resolve the same path as your browser.
- Fewer moving parts: no extra TLS layer or CDN rules in front of the bridge unless you add them later.

## Option B — Proxied / flattened DNS (e.g. Cloudflare orange cloud)

Many CDNs **do not return** a visible `CNAME` for `caib.<apex>` to the public internet. Instead they publish **A/AAAA** records pointing at the CDN edge. TLS is often terminated at the CDN (certificate may be Let’s Encrypt, Cloudflare, or another CA).

Caib may still show the bridge as **working** (**Proxied / amber**) when:

- No CNAME is visible at `caib.<apex>`, **and**
- The name resolves to addresses, **and**
- **HTTPS** to `https://caib.<apex>/` presents a **valid certificate for that hostname**.

**Risks for bots and assistants**

- Some tools only follow **CNAME** data and may not treat the host as “pointing at the registry” even when browsers work.
- CDN features (**Bot Fight Mode, WAF, geo rules, rate limits**) can block or throttle non-browser clients that share an IP pool (e.g. cloud assistant egress).
- **Caching** or **transform rules** could alter responses unless explicitly disabled for API paths.
- If the proxy is misconfigured, you can get a valid certificate but **wrong origin** — rare, but direct CNAME makes intent clearer in DNS.

**When proxied is still reasonable**

- You already standardise on Cloudflare (or similar) for all subdomains.
- You accept the trade-off and will tune **WAF / bot** rules so legitimate API and assistant traffic is allowed.

## What to send your DNS admin

> Please add **`caib.<apex>`** as a **CNAME** to **`registry.caib.io`** (or the target shown in Caib), **DNS only / grey cloud**, unless product agrees to use CDN proxy — in that case ensure HTTPS works for `caib.<apex>` and that automated clients are not blocked by bot or WAF rules. See Caib’s spec: `https://user.caib.io/docs/cname-bridge-routing`

## Step after DNS: registry must answer on `caib.<apex>`

Caib’s user app also **GETs** `https://caib.<apex>/v1/entities?domain=<apex>&lifecycle=all` (public, no API key). If that does not return JSON with `items` and `total`, the **nginx / TLS vhost** on the registry side probably does not yet include `caib.<apex>` in `server_name`, or routing to the API is missing — even when a browser shows a green lock for the hostname.

## Caib UI labels

- **Direct (green):** public DNS shows a CNAME chain to the expected registry hostname.
- **Proxied (amber):** no visible CNAME, but HTTPS for `caib.<apex>` succeeds; read the risks above.

---

*Caib — tenant bridge routing. Subject to change; check the in-app Domain & DNS page for live targets.*