# JhoWeb auth.md

Guia de autenticação para agentes. O JhoWeb é um portal público de ferramentas
online. Catálogo, Markdown por ferramenta e páginas humanas são de acesso
anônimo: não há API key, token Bearer, fluxo OAuth nem registro de agente.

## Agent audience

Qualquer agente (HTTP, LLM, assistente) pode ler os endpoints públicos
anonimamente. Identifique-se com um User-Agent descritivo.

## Endpoints públicos (sem autenticação)

- Catálogo JSON: https://jhoweb.com.br/ai/tools.json
- OpenAPI: https://jhoweb.com.br/ai/openapi.json
- API Catalog (RFC 9727): https://jhoweb.com.br/.well-known/api-catalog
- Health: https://jhoweb.com.br/.well-known/health
- Markdown por tool: https://jhoweb.com.br/ai/<slug>.md
- llms.txt: https://jhoweb.com.br/llms.txt
- llms-full.txt: https://jhoweb.com.br/llms-full.txt
- Well-known llms: https://jhoweb.com.br/.well-known/llms.txt
- Página humana para IAs: https://jhoweb.com.br/para-ias.php

A maioria das ferramentas calcula no navegador do usuário. A consulta de CEP
chama a API pública ViaCEP a partir do cliente; o JhoWeb não intermedia com
credenciais próprias.

## Auth scheme

Nenhum para a superfície pública. Faça `GET` direto nos URLs acima.

Não existe Authorization Server OAuth 2.0 nem provedor OpenID Connect neste
domínio. Por isso os documentos de discovery **não são publicados** (de forma
intencional, não por omissão):

- https://jhoweb.com.br/.well-known/oauth-authorization-server — inexistente
- https://jhoweb.com.br/.well-known/openid-configuration — inexistente
- https://jhoweb.com.br/.well-known/oauth-protected-resource — inexistente

Publicar metadata OIDC/OAuth falsa (issuer, `authorization_endpoint`,
`token_endpoint`, `jwks_uri` inventados) induziria agentes a fluxos que nunca
emitiriam tokens. RFC 8414 / OpenID Connect Discovery descrevem um servidor
real; sem APIs protegidas por Bearer, o 404 nesses caminhos é a resposta correta.

## Agent registration

Não há registro de agente nem provisionamento de credenciais. Métodos
suportados:

- `anonymous`: leitura dos endpoints públicos listados acima. Nenhuma conta,
  credencial ou callback é criada.

Não existe `POST /agent/auth` nem `register_uri`. Resumo máquina
(Auth.md `agent_auth`):

```json
{
  "agent_auth": {
    "identity_types_supported": ["anonymous"],
    "anonymous": {
      "credential_types_supported": ["none"],
      "claim_uri": "https://jhoweb.com.br/ai/tools.json"
    },
    "register_uri": null
  }
}
```

## Quando OAuth/OIDC passaria a existir

Só se o JhoWeb passar a expor APIs protegidas que exijam access token. Nesse
caso seriam publicados, de forma real e operacional:

1. `/.well-known/oauth-protected-resource` (RFC 9728) apontando o AS
2. `/.well-known/oauth-authorization-server` (RFC 8414) e/ou
   `/.well-known/openid-configuration` (OIDC Discovery) com `issuer`,
   `authorization_endpoint`, `token_endpoint`, `jwks_uri`,
   `grant_types_supported` e `response_types_supported` válidos