# Domínio curinga (*.seudominio)

Escopo do token: `domains:write` (e `projects:read` para ler). O serviço precisa ser `public`.

Um **domínio curinga** (`*.azarod.com`) liga **todos** os subdomínios de um nível de um domínio seu a **um único serviço**. O serviço recebe o `Host` original e decide o que mostrar. Conta **1** domínio na cota, não importa quantos subdomínios existam.

## Quando usar

- **Multi-tenant ou multi-estúdio**: cada cliente ganha `cliente.seusite.com` sem você cadastrar um domínio por cliente. O app lê o `Host` e escolhe o conteúdo.
- **Ambientes efêmeros** por branch, preview ou usuário, quando o app mesmo cria os nomes.
- **Não use** se você tem poucos subdomínios fixos: domínios exatos são mais simples, e cada um pode apontar para um serviço diferente.

## Passo a passo

1. **Cadastre** o curinga no serviço, com `hostname` no formato `*.dominio` (um único `*`, no início, seguido de ponto e de um domínio completo).
2. **Crie no seu DNS** o que a resposta mandar:

   | Registro | Nome | Valor |
   |---|---|---|
   | `CNAME` | `*.azarod.com` | o alvo da resposta (`dns.value`, `cname.<domínio de apps>`) |
   | `TXT` | `_nebular-verify.azarod.com` | `nebular-verify=<token>` (de `verification.value`) |

   - O `TXT` fica no **apex** do curinga (`azarod.com`), **sem asterisco**. O nome antigo `_nebular-challenge.azarod.com` também vale.
   - Se o seu provedor de DNS **não aceita CNAME curinga**, use `A` (e `AAAA`, se vierem) em `*.azarod.com` com os IPs de `dns.alt`.
   - Com Cloudflare, deixe os registros em **DNS only** (nuvem cinza); o proxy laranja é recusado (`proxied`).
3. **Verifique**: espere o worker ou chame `POST .../domains/{d}/verify` até `status` ser `active`.

A verificação testa um nome **aleatório** sob o apex (algo como `a1b2c3d4e5f6.azarod.com`) e exige que ele resolva para a plataforma. Por isso criar só o registro `sharkking.azarod.com` **não** ativa o curinga: o registro precisa ser o curinga (`*`).

```bash
SUF=$(date +%s)-$RANDOM
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: curinga-proj-$SUF" \
  -d "{\"name\": \"demo-curinga-$SUF\"}" | jq -r '.id')
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"visibility\": \"public\", \"slug\": \"demo-curinga-$SUF\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.2\"}}" | jq -r '.id')

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/domains" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: curinga-add-$SUF" \
  -d "{\"hostname\": \"*.curinga-$SUF.exemplo.test\"}"
```
```json
{"id": "01jb7k6a5q8r7t2v4w6x8y0a4f", "hostname": "*.azarod.com", "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c", "status": "pending_dns",
 "wildcard": true, "covers_example": "exemplo.azarod.com",
 "dns": {"type": "CNAME", "name": "*.azarod.com", "value": "cname.nebularapp.xyz"},
 "verification": {"type": "TXT", "name": "_nebular-verify.azarod.com", "value": "nebular-verify=7f3a9c"},
 "primary": false, "redirect_code": 308,
 "created_at": "2026-10-19T14:03:11Z"}
```

Os campos novos são `wildcard` (sempre `true` aqui) e `covers_example` (um exemplo de host coberto). O restante é igual ao de um [domínio próprio](/dominios/dominio-proprio/), incluindo os [estados](/dominios/dominio-proprio/#estados).

### Pelo MCP

Com o [MCP da Nebular](/agents/mcp/), as tools `add_domain` e `list_domains` já aceitam o curinga:

```json
{"name": "add_domain",
 "arguments": {"project": "01jb7k3a5q8r7t2v4w6x8y0a1b", "service": "01jb7k4a5q8r7t2v4w6x8y0a2c",
               "hostname": "*.azarod.com", "idempotency_key": "azarod-curinga-1"}}
```

Entregue à pessoa os registros `dns` e `verification` do resultado (o agent não cria DNS) e depois chame `list_domains` até o `status` ser `active`.

### Verificar agora

`POST /v1/projects/{p}/services/{s}/domains/{d}/verify` (escopo `domains:write`, sem corpo) roda a checagem na hora e devolve o domínio com o `diagnostic` atualizado (`reason`, `message`, `txt_found`, `shadowed`). Com `reason = no_records`, falta o CNAME curinga; com `txt_missing`, falta o TXT no apex.

## O que é coberto (precedência)

Para cada requisição a plataforma decide nesta ordem:

1. **Domínios da plataforma** (`<slug>.nebularapp.xyz`, painel, auth) nunca entram na tabela de domínios.
2. **Domínio exato ativo vence sempre.** Se `loja.azarod.com` está cadastrado (em qualquer serviço ou time) e ativo, ele serve `loja.azarod.com`, não o curinga. Remover o exato devolve o host ao curinga.
3. **Curinga ativo**: `*.azarod.com` cobre **um nível**: `sharkking.azarod.com`.
4. **Fora do curinga:**
   - o **apex** `azarod.com` não é coberto; se quiser servi-lo, cadastre `azarod.com` à parte (conta mais um na cota);
   - **netos** não são cobertos: `a.sharkking.azarod.com` precisa de `*.sharkking.azarod.com`, outro curinga.

Só domínio com `status = active` roteia e recebe certificado. Um curinga `pending_dns`, `error` (DNS caído) ou sem serviço não serve nada. O curinga **serve direto**: não redireciona, não envia `Link: canonical` e ignora a política de domínios do serviço. O HSTS configurado vale para todos os hosts cobertos.

O curinga **nunca é o domínio primário** e **não redireciona** nem pode ser alvo de `redirect_to`. Variáveis como `PUBLIC_URL` e `NEBULAR_PRIMARY_DOMAIN` continuam usando um domínio exato.

### Domínios exatos sob o curinga

Na resposta, `diagnostic.shadowed` lista os domínios exatos **ativos do seu time** que estão sob o curinga (eles vencem), e `shadowed_others` conta os de outros times (o nome de outro time nunca aparece). Serve para você entender por que um host específico não cai no curinga.

## HTTPS por host, sob demanda

Não existe certificado curinga. Cada host sob o curinga recebe **o seu próprio certificado no primeiro acesso HTTPS**, e a verificação não pede nenhuma chave nem token do seu DNS.

- **Teto por apex por hora.** Para impedir que um curinga esgote a cota de emissão, a plataforma aprova no máximo **20 certificados novos por hora por apex** (padrão; a instalação pode alterar com `API_WILDCARD_ISSUE_PER_HOUR`). Acima disso a emissão é recusada com **429** e `Retry-After: 3600`; o navegador (ou a requisição seguinte) tenta de novo e passa quando a janela libera. Hosts que já têm certificado não consomem o teto, nem os domínios exatos.
- **Limite do Let's Encrypt.** A autoridade pública limita **50 certificados por semana por domínio registrado**. Um rollout de centenas de subdomínios novos pode levar **dias** para ter todos os certificados.
- **Recomendação:** antes de um lançamento, **pré-aqueça** os subdomínios principais, acessando cada um por HTTPS (`curl -sI https://sharkking.azarod.com`) com antecedência, espalhado ao longo das horas. O primeiro acesso de um visitante a um host sem certificado pode demorar alguns segundos ou falhar por um instante (e funcionar na tentativa seguinte).

Detalhes gerais em [TLS](/dominios/tls/).

## Cota e plano

O curinga conta **1** em `domains` e em `domains_per_service` ([Limites e cotas](/operacao/limites-e-cotas/)). A feature `features.wildcard_domains` do plano (`GET /v1/limits` e a conta) liga ou desliga o curinga; desligada, só o curinga é barrado e os domínios exatos continuam valendo. `features.custom_domains` desligada barra todos os domínios.

## Erros

| Resposta | `error` | Quando | Como resolver |
|---|---|---|---|
| `400` | `invalid_request` | nome fora do formato (`*`, `**.x.com`, `a.*.x.com`, `*x.com`), sufixo público (`*.com.br`, `*.github.io`, `*.vercel.app`) ou nome que cobriria a própria plataforma | Use `*.seudominio.com`, um domínio que seja seu, com um único `*` no início. |
| `409` | `domain_taken` | já existe um curinga igual ativo (ou desconfigurado) na plataforma, ou o seu time já tem o nome | Publique o TXT de posse no apex para provar que é seu (veja [Problemas comuns](/dominios/problemas-comuns/#conflict)), ou remova o duplicado. |
| `422` | `wildcard_not_allowed` | curinga com `redirect_to`, `PATCH` com `primary: true`, `redirect_to` num curinga, ou outro domínio redirecionando para um curinga | Curinga serve direto; use um domínio exato para primário e redirecionamentos. |
| `422` | `feature_not_allowed` (`feature`) | o plano não tem `features.wildcard_domains` (ou `features.custom_domains`) | Peça a mudança de plano; domínios exatos seguem funcionando. |
| `422` | `quota_exceeded` (`limit`) | cota de domínios do time ou do serviço | Remova um domínio ou peça aumento ([Limites e cotas](/operacao/limites-e-cotas/)). |
| `422` | `rate_limited` | mais de 30 domínios criados na última hora pelo time | Espere `Retry-After`. |
| `429` | (resposta do HTTPS do host, não da API) | teto de emissões de certificado do apex | Espere; o navegador tenta de novo. Veja acima. |
| `404` | `not_found` | domínio de outro time ou serviço | Confira os identificadores. |

Um nome fora do formato volta `400`:

```bash
SUF=$(date +%s)-$RANDOM
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
  -d "{\"name\": \"demo-curinga-$SUF\"}" | jq -r .id)
S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \
  -d "{\"visibility\": \"public\", \"slug\": \"demo-curinga-$SUF\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.2\"}}" | jq -r .id)

curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/domains" -H "$H" -H "Content-Type: application/json" \
  -d "{\"hostname\": \"a.*.exemplo.test\"}"
```
```json
{"error": "invalid_request", "message": "Use o curinga no formato *.seudominio.com: um único * no início, seguido de ponto e de um domínio completo."}
```

O curinga que **não ativa** é diagnosticado como qualquer domínio: veja `diagnostic.message` (cita o registro curinga certo) e [Problemas comuns](/dominios/problemas-comuns/).

## Exemplo: plataforma multi-estúdio com Next.js

Cenário: `*.azarod.com` aponta para **um** serviço Next.js; `sharkking.azarod.com` mostra o estúdio "sharkking". O apex e o `www` ficam no site principal.

1. Cadastre `*.azarod.com` no serviço da plataforma de estúdios (esta página).
2. Cadastre `azarod.com` e `www.azarod.com` no serviço do site principal (domínios exatos; vencem o curinga no `www`).
3. Cadastre como domínios exatos, em outros serviços, os nomes reservados que não são estúdios (`api.azarod.com`, `auth.azarod.com`, `admin.azarod.com`), ou trate-os no app, como abaixo.

Roteamento por `Host` no `middleware.ts`:

```ts
import { NextRequest, NextResponse } from 'next/server';

const APEX = 'azarod.com';
const RESERVADOS = new Set(['www', 'api', 'auth', 'admin', 'app', 'mail']);

// middleware roteia a requisição pelo Host: apex e www vão para o site principal, nomes reservados
// e hosts desconhecidos retornam 404 do próprio app, e o resto reescreve para a árvore do estúdio.
export function middleware(req: NextRequest) {
  // A Nebular repassa o Host original e define x-forwarded-host com o host da requisição.
  const host = (req.headers.get('x-forwarded-host') ?? req.headers.get('host') ?? '')
    .toLowerCase().split(':')[0];

  if (host === APEX || host === `www.${APEX}`) return NextResponse.next(); // site principal
  if (!host.endsWith(`.${APEX}`)) return new NextResponse('Não encontrado', { status: 404 });

  const estudio = host.slice(0, -(APEX.length + 1)); // só um nível: o curinga não cobre netos
  if (!estudio || estudio.includes('.') || RESERVADOS.has(estudio) || !/^[a-z0-9-]{1,40}$/.test(estudio)) {
    return new NextResponse('Não encontrado', { status: 404 });
  }

  const url = req.nextUrl.clone();
  url.pathname = `/estudios/${estudio}${req.nextUrl.pathname}`;
  const res = NextResponse.rewrite(url);
  res.headers.set('x-estudio', estudio); // as páginas validam se o estúdio existe e dão notFound() se não
  return res;
}

export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };
```

Boas práticas do caso multi-estúdio:

- **Host desconhecido = 404 do app.** A plataforma entrega *qualquer* subdomínio do curinga ao serviço; quem sabe quais estúdios existem é o app. Faça a página do estúdio chamar `notFound()` quando ele não existir.
- **Reservados:** trate `www`, `api`, `auth`, `admin` no app (404 ou redirecionamento) ou cadastre-os como domínios exatos em outros serviços (o exato vence).
- **Cookie de sessão SEM `Domain=`.** Sem o atributo `Domain`, o cookie fica preso ao host que o criou (`sharkking.azarod.com`) e **não vaza** para os outros estúdios. Com `Domain=.azarod.com`, qualquer estúdio leria a sessão dos demais. Use também `Secure`, `HttpOnly` e `SameSite=Lax`.
- `NEXT_PUBLIC_*` e URLs absolutas: monte a URL a partir do `Host` da requisição, não da variável `PUBLIC_URL` (que vem de um domínio exato).

## Para agents

Resumo para LLM:

- Cadastrar: `POST /v1/projects/{p}/services/{s}/domains` com `{"hostname": "*.dominio.com"}`; escopo `domains:write`; o serviço precisa ser `public`. Pelo MCP: `add_domain`, depois `list_domains`.
- Resposta traz `wildcard: true`, `covers_example`, `dns` (CNAME em `*.dominio`; alternativa A/AAAA em `dns.alt`) e `verification` (TXT `_nebular-verify.<apex>`, **sem asterisco**, no apex). Entregue esses registros a uma pessoa: o agent não cria DNS.
- Acompanhe com `GET` ou `verify` até `status = active`; siga `diagnostic.message` se parar.
- Cobre **um nível**; o apex e os netos não são cobertos; domínio exato ativo vence; curinga não é primário e não redireciona.
- HTTPS por host no primeiro acesso; teto de 20 emissões/hora por apex (`429` + `Retry-After`: espere e tente de novo, não é falha); limite do Let's Encrypt de 50 certificados por semana por domínio registrado; pré-aqueça os hosts principais.
- Erros: `400 invalid_request` (nome), `409 domain_taken`, `422 wildcard_not_allowed`, `422 feature_not_allowed`, `422 quota_exceeded`. Não repita sem alterar a requisição.
- O app roteia por `Host`/`X-Forwarded-Host`; host desconhecido deve responder 404 pelo próprio app; cookie de sessão sem `Domain=`.

Veja também [Domínio próprio](/dominios/dominio-proprio/), [Redirecionamentos](/dominios/redirecionamentos/), [TLS](/dominios/tls/) e [Referência de domínios](/referencia/dominios/).
